home *** CD-ROM | disk | FTP | other *** search
/ MacHack 1996 / MacHack 1996.toast / Hacks / Hacks ’87 / Inside Mac DA ƒ / Manual < prev    next >
Encoding:
Text File  |  1987-03-10  |  590.2 KB  |  15,577 lines  |  [TEXT/MPS ]
  1.  ,129
  2. 129
  3. Resource Manager Definitions.
  4.  
  5. CONST
  6.       resSysHeap    = 64;   { System or application heap? }
  7.       resPurgeable  = 32;   { Purgeable resource? }
  8.       resLocked     = 16;   { Load it in locked? }
  9.       resProtected  = 8;    { Protected? }
  10.       resPreload    = 4;    { Load in on OpenResFile? }
  11.       resChanged    = 2;    { Resource changed? }
  12.  
  13.       mapReadOnly   = 128;  { Resource file read-only }
  14.       mapCompact    = 64;   { Compact resource file }
  15.       mapChanged    = 32;   { Write map out at update }
  16.  
  17.       resNotFound   = - 192; { Resource not found }
  18.       resFNotFound  = - 193; { Resource file not found }
  19.       addResFailed  = - 194; { AddResource failed }
  20.       rmvResFailed  = - 196; { RmveResource failed }
  21.       resAttrErr    = -198;  {attribute does not permit operation}
  22.       mapReadErr    = -199;  {map does not permit operation}
  23.  
  24. Resources in 128 Ko ROM:
  25.  
  26. 'CURS'  1   IBeamCursor
  27. 'CURS'  2   CrossCursor
  28. 'CURS'  3   PlusCursor
  29. 'CURS'  4   WatchCursor
  30. 'DRVR'  2   Printer Driver shell (.PRINT)
  31. 'DRVR'  3   Sound Driver  (.SOUND)
  32. 'DRVR'  4   Disk Driver  (.SONY)
  33. 'DRVR'  9   AppleTalk driver  (.MPP)
  34. 'DRVR'  A   AppleTalk driver  (.ATP)
  35. 'FONT'  0   Name of system font
  36. 'FONT'  C   System font
  37. 'MDEF'  0   Default menu definition procedure
  38. 'PACK'  4   Floating-Point Arithmetic Package
  39. 'PACK'  5   Transcendental Functions Package
  40. 'PACK'  7   Binary-Decimal Conversion Package
  41. 'SERD'  0   Serial Driver
  42. 'WDEF'  0   Default window definition function
  43.  
  44. TYPE
  45.  
  46.       ResType = PACKED ARRAY [1..4] OF CHAR;
  47.  
  48. \ ,130
  49. 130
  50. QuickDraw Definitions.
  51.  
  52. CONST
  53.       srcCopy       = 0; { the 16 transfer modes }
  54.       srcOr         = 1;
  55.       srcXor        = 2;
  56.       srcBic        = 3;
  57.       notSrcCopy    = 4;
  58.       notSrcOr      = 5;
  59.       notSrcXor     = 6;
  60.       notSrcBic     = 7;
  61.       patCopy       = 8;
  62.       patOr         = 9;
  63.       patXor        = 10;
  64.       patBic        = 11;
  65.       notPatCopy    = 12;
  66.       notPatOr      = 13;
  67.       notPatXor     = 14;
  68.       notPatBic     = 15;
  69.  
  70.       { QuickDraw color separation constants }
  71.  
  72.       normalBit     = 0; { normal screen mapping }
  73.       inverseBit    = 1; { inverse screen mapping }
  74.       redBit        = 4; { RGB additive mapping }
  75.       greenBit      = 3;
  76.       blueBit       = 2;
  77.       cyanBit       = 8; { CMYBk subtractive mapping }
  78.       magentaBit    = 7;
  79.       yellowBit     = 6;
  80.       blackBit      = 5;
  81.  
  82.       blackColor    = 33; { colors expressed in these mappings }
  83.       whiteColor    = 30;
  84.       redColor      = 205;
  85.       greenColor    = 341;
  86.       blueColor     = 409;
  87.       cyanColor     = 273;
  88.       magentaColor  = 137;
  89.       yellowColor   = 69;
  90.  
  91.       picLParen     = 0;   { standard picture comments }
  92.       picRParen     = 1;
  93.  
  94.       iBeamCursor   = 1; {text selection cursor}
  95.       crossCursor   = 2; {for drawing graphics}
  96.       plusCursor    = 3; {for structured selection}
  97.       watchCursor   = 4; {for indicating a long delay}
  98.  
  99. TYPE
  100.       QDByte = SignedByte;
  101.       QDPtr = Ptr; { blind pointer }
  102.       QDHandle = Handle; { blind handle }
  103.       Pattern = PACKED ARRAY [0..7] OF 0..255;
  104.       Bits16 = ARRAY [0..15] OF INTEGER;
  105.       VHSelect = (v, h);
  106.       GrafVerb = (frame, paint, erase, invert, fill);
  107.       StyleItem = (bold, italic, underline, outline, shadow, condense,
  108.                     extend);
  109.       Style = SET OF StyleItem;
  110.  
  111.       FontInfo = RECORD
  112.                    ascent: INTEGER;
  113.                    descent: INTEGER;
  114.                    widMax: INTEGER;
  115.                    leading: INTEGER;
  116.                  END;
  117.  
  118.       Point = RECORD
  119.                 CASE INTEGER OF
  120.  
  121.                   0:
  122.                     (v: INTEGER;
  123.                      h: INTEGER);
  124.  
  125.                   1:
  126.                     (vh: ARRAY [VHSelect] OF INTEGER);
  127.  
  128.               END;
  129.  
  130.       Rect = RECORD
  131.                CASE INTEGER OF
  132.  
  133.                  0:
  134.                    (top: INTEGER;
  135.                     left: INTEGER;
  136.                     bottom: INTEGER;
  137.                     right: INTEGER);
  138.  
  139.                  1:
  140.                    (topLeft: Point;
  141.                     botRight: Point);
  142.              END;
  143.  
  144.       BitMap = RECORD
  145.                  baseAddr: Ptr;
  146.                  rowBytes: INTEGER;
  147.                  bounds: Rect;
  148.                END;
  149.  
  150.       Cursor = RECORD
  151.                  data: Bits16;
  152.                  mask: Bits16;
  153.                  hotSpot: Point;
  154.                END;
  155.  
  156.       PenState = RECORD
  157.                    pnLoc: Point;
  158.                    pnSize: Point;
  159.                    pnMode: INTEGER;
  160.                    pnPat: Pattern;
  161.                  END;
  162.  
  163.       PolyHandle = ^PolyPtr;
  164.       PolyPtr = ^Polygon;
  165.       Polygon = RECORD
  166.                   polySize: INTEGER;
  167.                   polyBBox: Rect;
  168.                   polyPoints: ARRAY [0..0] OF Point;
  169.                 END;
  170.  
  171.       RgnHandle = ^RgnPtr;
  172.       RgnPtr = ^Region;
  173.       Region = RECORD
  174.                  rgnSize: INTEGER; { rgnSize = 10 for rectangular }
  175.                  rgnBBox: Rect;
  176.                         { plus more data if not rectangular }
  177.                END;
  178.  
  179.       PicHandle = ^PicPtr;
  180.       PicPtr = ^Picture;
  181.       Picture = RECORD
  182.                   picSize: INTEGER;
  183.                   picFrame: Rect;
  184.                           { plus byte codes for picture content }
  185.                 END;
  186.  
  187.       QDProcsPtr = ^QDProcs;
  188.       QDProcs = RECORD
  189.                   textProc: Ptr;
  190.                   lineProc: Ptr;
  191.                   rectProc: Ptr;
  192.                   rRectProc: Ptr;
  193.                   ovalProc: Ptr;
  194.                   arcProc: Ptr;
  195.                   polyProc: Ptr;
  196.                   rgnProc: Ptr;
  197.                   bitsProc: Ptr;
  198.                   commentProc: Ptr;
  199.                   txMeasProc: Ptr;
  200.                   getPicProc: Ptr;
  201.                   putPicProc: Ptr;
  202.                 END;
  203.  
  204.       GrafPtr = ^GrafPort;
  205.       GrafPort = RECORD
  206.                    device: INTEGER;
  207.                    portBits: BitMap;
  208.                    portRect: Rect;
  209.                    visRgn: RgnHandle;
  210.                    clipRgn: RgnHandle;
  211.                    bkPat: Pattern;
  212.                    fillPat: Pattern;
  213.                    pnLoc: Point;
  214.                    pnSize: Point;
  215.                    pnMode: INTEGER;
  216.                    pnPat: Pattern;
  217.                    pnVis: INTEGER;
  218.                    txFont: INTEGER;
  219.                    txFace: Style;
  220.                    txMode: INTEGER;
  221.                    txSize: INTEGER;
  222.                    spExtra: Fixed;
  223.                    fgColor: LongInt;
  224.                    bkColor: LongInt;
  225.                    colrBit: INTEGER;
  226.                    patStretch: INTEGER;
  227.                    picSave: Handle;
  228.                    rgnSave: Handle;
  229.                    polySave: Handle;
  230.                    grafProcs: QDProcsPtr;
  231.                  END;
  232.  
  233.     VAR
  234.       thePort: GrafPtr;
  235.       white: Pattern;
  236.       black: Pattern;
  237.       gray: Pattern;
  238.       ltGray: Pattern;
  239.       dkGray: Pattern;
  240.       arrow: Cursor;
  241.       screenBits: BitMap;
  242.       randSeed: LongInt;
  243.  
  244. \ ,131
  245. 131
  246. Font Manager Definitions.
  247.  
  248. CONST
  249.  
  250.       commandMark   = $11;
  251.       checkMark     = $12;
  252.       diamondMark   = $13;
  253.       appleMark     = $14;
  254.  
  255.       systemFont    = 0;
  256.       applFont      = 1;
  257.       newYork       = 2;
  258.       geneva        = 3;
  259.       monaco        = 4;
  260.       venice        = 5;
  261.       london        = 6;
  262.       athens        = 7;
  263.       sanFran       = 8;
  264.       toronto       = 9;
  265.       cairo         = 11;
  266.       losAngeles    = 12;
  267.       times         = 20;
  268.       helvetica     = 21;
  269.       courier       = 22;
  270.       symbol        = 23;
  271.       mobile        = 24;
  272.  
  273.       propFont      = $9000;
  274.       prpFntH       = $9001;
  275.       prpFntW       = $9002;
  276.       prpFntHW      = $9003;
  277.  
  278.       fixedFont     = $B000;
  279.       fxdFntH       = $B001;
  280.       fxdFntW       = $B002;
  281.       fxdFntHW      = $B003;
  282.  
  283.       fontWid       = $ACB0;
  284.  
  285. TYPE
  286.  
  287.       FMInput = PACKED RECORD
  288.                   family: INTEGER;
  289.                   size: INTEGER;
  290.                   face: Style;
  291.                   needBits: BOOLEAN;
  292.                   device: INTEGER;
  293.                   numer: Point;
  294.                   denom: Point;
  295.                 END;
  296.  
  297.       FMOutPtr = ^FMOutPut;
  298.  
  299.       FMOutPut = PACKED RECORD
  300.                    errNum: INTEGER;
  301.                    fontHandle: Handle;
  302.                    bold: Byte;
  303.                    italic: Byte;
  304.                    ulOffset: Byte;
  305.                    ulShadow: Byte;
  306.                    ulThick: Byte;
  307.                    shadow: Byte;
  308.                    extra: SignedByte;
  309.                    ascent: Byte;
  310.                    descent: Byte;
  311.                    widMax: Byte;
  312.                    leading: SignedByte;
  313.                    unused: Byte;
  314.                    numer: Point;
  315.                    denom: Point;
  316.                  END;
  317.  
  318.       FontRec = RECORD
  319.                   fontType: INTEGER;    { font type }
  320.                   firstChar: INTEGER;   { ASCII code of first character }
  321.                   lastChar: INTEGER;    { ASCII code of last character }
  322.                   widMax: INTEGER;      { maximum character width }
  323.                   kernMax: INTEGER;     { negative of maximum character kern }
  324.                   nDescent: INTEGER;    { negative of descent }
  325.                   fRectWidth: INTEGER;  { width of font rectangle }
  326.                   fRectHeight: INTEGER; { height of font rectangle }
  327.                   oWTLoc: INTEGER;      { offset to offset/width table }
  328.                   ascent: INTEGER;      { ascent }
  329.                   descent: INTEGER;     { descent }
  330.                   leading: INTEGER;     { leading }
  331.                   rowWords: INTEGER;    { row width of bit image / 2 }
  332.                 { bitImage:    ARRAY[1..rowWords,1..fRectHeight]
  333.                                     OF INTEGER;
  334.                   locTable:    ARRAY[firstChar..lastChar+2]
  335.                                     OF INTEGER;
  336.                   owTable:    ARRAY[firstChar..lastChar+2]
  337.                                     OF INTEGER;
  338.                   widthTable: ARRAY[firstChar..lastChar+2]
  339.                                     OF INTEGER;
  340.                   heightTable: ARRAY[firstChar..lastChar+2]
  341.                                     OF INTEGER; }
  342.                 END;
  343.  
  344.       {new 128K ROM}
  345.  
  346.       FMetricRec = RECORD
  347.                      ascent: Fixed;     {base line to top}
  348.                      descent: Fixed;    {base line to bottom}
  349.                      leading: Fixed;    {leading between lines}
  350.                      widMax: Fixed;     {maximum character width}
  351.                      wTabHandle: Fixed; {handle to font width table}
  352.                    END;
  353.  
  354.       WidTable = RECORD
  355.                    numWidths: INTEGER; {number of entries - 1}
  356.                             {widList: ARRAY[1..numWidths] of WidEntry}
  357.                  END;
  358.  
  359.       WidEntry = RECORD
  360.                    widStyle: INTEGER; {style entry applies to}
  361.                                       {widRec: ARRAY[firstChar..lastChar]
  362.                                         of INTEGER}
  363.                  END;
  364.  
  365.       AsscEntry = RECORD
  366.                     fontSize: INTEGER;
  367.                     fontStyle: INTEGER;
  368.                     fontID: INTEGER; {font resource ID}
  369.                   END;
  370.  
  371.       FontAssoc = RECORD
  372.                     numAssoc: INTEGER; {number of entries - 1}
  373.                             {asscTable: ARRAY[1..numAssoc] OF AsscEntry}
  374.                   END;
  375.  
  376.       StyleTable = RECORD
  377.                      fontClass: INTEGER;
  378.                      offset: LongInt;
  379.                      reserved: LongInt;
  380.                      indexes: ARRAY [0..47] OF Byte;
  381.                    END;
  382.  
  383.       NameTable = RECORD
  384.                     stringCount: INTEGER;
  385.                     baseFontName: STR255;
  386.                                 {strings: ARRAY[2..stringCount]  OF STRING}
  387.                                 {the lengths of the strings are arbitrary}
  388.                   END;
  389.  
  390.       KernPair = RECORD
  391.                    kernFirst: CHAR; {1st character of kerned pair}
  392.                    kernSecond: CHAR; {2nd character of kerned pair}
  393.                    kernWidth: INTEGER; {kerning in 1pt fixed format}
  394.                  END;
  395.  
  396.       KernEntry = RECORD
  397.                     kernLength: INTEGER; {length of this entry}
  398.                     kernStyle: INTEGER; {style the entry applies to}
  399.                              {kernRec: ARRAY[1..(kernLength/4)-1] OF KernPair}
  400.                   END;
  401.  
  402.       KernTable = RECORD
  403.                     numKerns: INTEGER; {number of kerning entries}
  404.                             {kernList: ARRAY[1..numKerns] OF KernEntry}
  405.                   END;
  406.  
  407.       WidthTable = PACKED RECORD
  408.                      tabData: ARRAY [1..256] OF Fixed; {character widths}
  409.                      tabFont: Handle; {font record used to build table}
  410.                      sExtra: LongInt; {space extra used for table}
  411.                      Style: LongInt; {extra due to style}
  412.                      fID: INTEGER; {font family ID}
  413.                      fSize: INTEGER; {font size request}
  414.                      face: INTEGER; {style (face) request}
  415.                      device: INTEGER; {device requested}
  416.                      vInScale: Fixed; {scale factors requested}
  417.                      hInScale: Fixed; {scale factors requested}
  418.                      aFID: INTEGER; {actual font family ID for table}
  419.                      fHand: Handle; {family record used to build up table}
  420.                      usedFam: BOOLEAN; {used fixed point family widths}
  421.                      aFace: Byte; {actual face produced}
  422.                      vOutput: INTEGER; {vertical scale output value}
  423.                      hOutput: INTEGER; {horizontal scale output value}
  424.                      vFactor: INTEGER; {vertical scale output value}
  425.                      hFactor: INTEGER; {horizontal scale output value}
  426.                      aSize: INTEGER; {actual size of actual font used}
  427.                      tabSize: INTEGER; {total size of table}
  428.                    END;
  429.  
  430.       FamRec = RECORD
  431.                  ffFlags: INTEGER; {flags for family}
  432.                  ffFamID: INTEGER; {family ID number}
  433.                  ffFirstChar: INTEGER; {ASCII code of 1st character}
  434.                  ffLastChar: INTEGER; {ASCII code of last character}
  435.                  ffAscent: INTEGER; {maximum ascent for 1pt font}
  436.                  ffDescent: INTEGER; {maximum descent for 1pt font}
  437.                  ffLeading: INTEGER; {maximum leading for 1pt font}
  438.                  ffWidMax: INTEGER; {maximum widMax for 1pt font}
  439.                  ffWTabOff: LongInt; {offset to width table}
  440.                  ffKernOff: LongInt; {offset to kerning table}
  441.                  ffStylOff: LongInt; {offset to style mapping table}
  442.                  ffProperty: ARRAY [1..9] OF INTEGER; {style property info}
  443.                  ffIntl: ARRAY [1..2] OF INTEGER; {for international use}
  444.                  ffVersion: INTEGER; {version number}
  445.                           {ffAssoc:    FontAssoc;} {font association table}
  446.                           {ffWidthTab: WidTable;} {width table}
  447.                           {ffStyTab:   StyleTable;} {style mapping table}
  448.                           {ffKernTab:  KernTable;} {kerning table}
  449.                END;
  450.  
  451. \ ,132
  452. 132
  453. Event Manager Definitions.
  454.  
  455. CONST
  456.  
  457.       everyEvent    = - 1;
  458.       NullEvent     = 0;
  459.       mouseDown     = 1;
  460.       mouseUp       = 2;
  461.       keyDown       = 3;
  462.       keyUp         = 4;
  463.       autoKey       = 5;
  464.       updateEvt     = 6;
  465.       diskEvt       = 7;
  466.       activateEvt   = 8;
  467.       networkEvt    = 10;
  468.       driverEvt     = 11;
  469.       app1Evt       = 12;
  470.       app2Evt       = 13;
  471.       app3Evt       = 14;
  472.       app4Evt       = 15;
  473.  
  474.       { event mask equates }
  475.       mDownMask     = 2;
  476.       mUpMask       = 4;
  477.       keyDownMask   = 8;
  478.       keyUpMask     = 16;
  479.       autoKeyMask   = 32;
  480.       updateMask    = 64;
  481.       diskMask      = 128;
  482.       activMask     = 256;
  483.       networkMask   = 1024;
  484.       driverMask    = 2048;
  485.       app1Mask      = 4096;
  486.       app2Mask      = 8192;
  487.       app3Mask      = 16384;
  488.       app4Mask      = - 32768;
  489.  
  490.       {to decipher event message for keyDown events}
  491.       charCodeMask  = $000000FF;
  492.       keyCodeMask   = $0000FF00;
  493.  
  494.       { modifiers }
  495.       optionKey     = 2048; { Bit 3 of high byte }
  496.       alphaLock     = 1024; { Bit 2 }
  497.       ShiftKey      = 512;  { Bit 1 }
  498.       CmdKey        = 256;  { Bit 0 }
  499.       BtnState      = 128;  { Bit 7 of low byte is mouse button state }
  500.  
  501.       activeFlag    = 1;    { bit 0 of modifiers for activate event }
  502.  
  503.       {error for PostEvent}
  504.       EvtNotEnb     = 1;
  505.  
  506. TYPE
  507.  
  508.       EventRecord = RECORD
  509.                       what: INTEGER;
  510.                       message: LongInt;
  511.                       when: LongInt;
  512.                       where: Point;
  513.                       modifiers: INTEGER;
  514.                     END;
  515.  
  516.       KeyMap = PACKED ARRAY [0..127] OF BOOLEAN;
  517.  
  518. \ ,133
  519. 133
  520. Window Manager Definitions.
  521.  
  522. CONST
  523.  
  524.       {window messages}
  525.       wDraw     = 0;
  526.       wHit      = 1;
  527.       wCalcRgns = 2;
  528.       wNew      = 3;
  529.       wDispose  = 4;
  530.       wGrow     = 5;
  531.       wDrawGIcon = 6;
  532.  
  533.       {types of windows}
  534.       dialogKind    = 2;
  535.       userKind      = 8;
  536.  
  537.       {desk pattern resource ID}
  538.       deskPatID     = 16;
  539.  
  540.       {window definition procedure IDs}
  541.       documentProc  = 0;
  542.       dBoxProc      = 1;
  543.       plainDBox     = 2;
  544.       altDBoxProc   = 3;
  545.       noGrowDocProc = 4;
  546.       zoomDocProc   = 8;
  547.       zoomNoGrow    = 12;
  548.       rDocProc      = 16;
  549.  
  550.       {FindWindow Result Codes}
  551.       inDesk        = 0;
  552.       inMenuBar     = 1;
  553.       inSysWindow   = 2;
  554.       inContent     = 3;
  555.       inDrag        = 4;
  556.       inGrow        = 5;
  557.       inGoAway      = 6;
  558.  
  559.       {new 128K ROM}
  560.       inZoomIn      = 7;
  561.       inZoomOut     = 8;
  562.  
  563.       {defProc hit test codes}
  564.       wNoHit        = 0;
  565.       wInContent    = 1;
  566.       wInDrag       = 2;
  567.       wInGrow       = 3;
  568.       wInGoAway     = 4;
  569.  
  570.       {new 128K ROM}
  571.       wInZoomIn     = 5;
  572.       wInZoomOut    = 6;
  573.  
  574.       {axis constraints for DragGrayRgn call}
  575.       noConstraint  = 0;
  576.       hAxisOnly     = 1;
  577.       vAxisOnly     = 2;
  578.  
  579. TYPE
  580.  
  581.       WindowPtr     = GrafPtr;
  582.       WindowPeek    = ^WindowRecord;
  583.       ControlHandle = ^ControlPtr; {for Control Manager}
  584.  
  585.       WStateData =  RECORD;
  586.         userState:  Rect;   {user state}
  587.         stdState:   Rect    {standard state}
  588.       END;
  589.  
  590.       WindowRecord = RECORD
  591.                        port: GrafPort;
  592.                        windowKind: INTEGER;
  593.                        visible: BOOLEAN;
  594.                        hilited: BOOLEAN;
  595.                        goAwayFlag: BOOLEAN;
  596.                        spareFlag: BOOLEAN;
  597.                        strucRgn: RgnHandle;
  598.                        contRgn: RgnHandle;
  599.                        updateRgn: RgnHandle;
  600.                        windowDefProc: Handle;
  601.                        dataHandle: Handle;
  602.                        titleHandle: StringHandle;
  603.                        titleWidth: INTEGER;
  604.                        ControlList: ControlHandle;
  605.                        nextWindow: WindowPeek;
  606.                        windowPic: PicHandle;
  607.                        refCon: LongInt;
  608.                      END;
  609.  
  610. \ ,134
  611. 134
  612. Control Manager Definitions.
  613.  
  614. CONST
  615.  
  616.       {control messages}
  617.       drawCntl  = 0;
  618.       testCntl  = 1;
  619.       calcCRgns = 2;
  620.       initCntl  = 3;
  621.       dispCntl  = 4;
  622.       posCntl   = 5;
  623.       thumbCntl = 6;
  624.       dragCntl  = 7;
  625.       autoTrack = 8;
  626.  
  627.       {FindControl Result Codes}
  628.       inButton      = 10;
  629.       inCheckbox    = 11;
  630.       inUpButton    = 20;
  631.       inDownButton  = 21;
  632.       inPageUp      = 22;
  633.       inPageDown    = 23;
  634.       inThumb       = 129;
  635.  
  636.       {control definition proc ID's}
  637.       pushButProc   = 0;
  638.       checkBoxProc  = 1;
  639.       radioButProc  = 2;
  640.       scrollBarProc = 16;
  641.  
  642.       useWFont      = 8;
  643.  
  644. TYPE
  645.       ControlPtr = ^ControlRecord;
  646.  
  647.       ControlRecord = PACKED RECORD
  648.                         nextControl: ControlHandle;
  649.                         contrlOwner: WindowPtr;
  650.                         contrlRect: Rect;
  651.                         contrlVis: Byte;
  652.                         contrlHilite: Byte;
  653.                         contrlValue: INTEGER;
  654.                         contrlMin: INTEGER;
  655.                         contrlMax: INTEGER;
  656.                         contrlDefProc: Handle;
  657.                         contrlData: Handle;
  658.                         contrlAction: ProcPtr;
  659.                         contrlrfCon: LongInt;
  660.                         contrlTitle: STR255;
  661.                       END; {ControlRecord}
  662.  
  663.  
  664. \ ,135
  665. 135
  666. Menu Manager Definitions.
  667.  
  668. CONST
  669.       noMark        = 0; { mark symbol for MarkItem }
  670.       TextMenuProc  = 0;
  671.  
  672.       { menu defProc messages }
  673.       mDrawMsg      = 0;
  674.       mChooseMsg    = 1;
  675.       mSizeMsg      = 2;
  676.  
  677. TYPE
  678.       MenuPtr       = ^MenuInfo;
  679.       MenuHandle    = ^MenuPtr;
  680.       MenuInfo      = RECORD
  681.                        menuId: INTEGER;
  682.                        menuWidth: INTEGER;
  683.                        menuHeight: INTEGER;
  684.                        menuProc: Handle;
  685.                        enableFlags: LongInt;
  686.                        menuData: STR255;
  687.                      END;
  688.  
  689. \ ,136
  690. 136
  691. TextEdit Definitions.
  692.  
  693. CONST
  694.       teJustLeft    = 0;
  695.       teJustRight   = - 1;
  696.       teJustCenter  = 1;
  697.  
  698. TYPE
  699.       TERec = RECORD
  700.                 destRect: Rect;         {Destination rectangle}
  701.                 viewRect: Rect;         {view rectangle}
  702.                 selRect: Rect;          {Select rectangle}
  703.                 lineHeight: INTEGER;    {Current font lineheight}
  704.                 fontAscent: INTEGER;    {Current font ascent}
  705.                 selPoint: Point;        {Selection point(mouseLoc)}
  706.  
  707.                 selStart: INTEGER;      {Selection start}
  708.                 selEnd: INTEGER;        {Selection end}
  709.  
  710.                 active: INTEGER;        {<>0 if active}
  711.  
  712.                 wordBreak: ProcPtr;     {Word break routine}
  713.                 clikLoop: ProcPtr;      {Click loop routine}
  714.  
  715.                 clickTime: LongInt;     {Time of first click}
  716.                 clickLoc: INTEGER;      {Char. location of click}
  717.  
  718.                 caretTime: LongInt;     {Time for next caret blink}
  719.                 caretState: INTEGER;    {On/active booleans}
  720.  
  721.                 just: INTEGER;          {fill style}
  722.  
  723.                 teLength: INTEGER;      {Length of text below}
  724.                 hText: Handle;          {Handle to actual text}
  725.  
  726.                 recalBack: INTEGER;     {<>0 if recal in background}
  727.                 recalLines: INTEGER;    {Line being recal'ed}
  728.                 clikStuff: INTEGER;     {click stuff (internal)}
  729.  
  730.                 crOnly: INTEGER;        {Set to -1 if CR line breaks only}
  731.  
  732.                 txFont: INTEGER;        {Text Font}
  733.                 txFace: Style;          {Text Face}
  734.                 txMode: INTEGER;        {Text Mode}
  735.                 txSize: INTEGER;        {Text Size}
  736.  
  737.                 inPort: GrafPtr;        {Grafport}
  738.  
  739.                 highHook: ProcPtr;      {Highlighting hook}
  740.                 caretHook: ProcPtr;     {Highlighting hook}
  741.  
  742.                 nLines: INTEGER;        {Number of lines}
  743.                 lineStarts: ARRAY [0..16000] OF INTEGER;
  744.                                         {Actual line starts
  745.                                         themselves}
  746.               END;                      {RECORD}
  747.       TEPtr = ^TERec;
  748.       TEHandle = ^TEPtr;
  749.  
  750.       CharsHandle = ^CharsPtr;
  751.       CharsPtr = ^Chars;
  752.       Chars = PACKED ARRAY [0..32000] OF CHAR;
  753.  
  754. \ ,137
  755. 137
  756. Dialog Manager Definitions.
  757.  
  758. CONST
  759.       userItem  = 0;
  760.       ctrlItem  = 4;
  761.       btnCtrl   = 0;    { Low two bits specify what kind of control }
  762.       chkCtrl   = 1;
  763.       radCtrl   = 2;
  764.       resCtrl   = 3;
  765.  
  766.       statText      = 8;        { Static text }
  767.       editText      = 16;       { Editable text }
  768.       iconItem      = 32;       { Icon item }
  769.       picItem       = 64;       { Picture item }
  770.       itemDisable   = 128;      { Disable item if set }
  771.  
  772.       ok        = 1;        { OK button is first by convention }
  773.       cancel    = 2;        { Cancel button is second by convention }
  774.  
  775.       stopIcon      = 0;
  776.       noteIcon      = 1;
  777.       cautionIcon   = 2;
  778.  
  779. TYPE
  780.       DialogPtr    = WindowPtr;
  781.       DialogPeek   = ^DialogRecord;
  782.       DialogRecord = RECORD
  783.                        window: WindowRecord;
  784.                        Items: Handle;
  785.                        textH: TEHandle;
  786.                        editField: INTEGER;
  787.                        editOpen: INTEGER;
  788.                        aDefItem: INTEGER;
  789.                      END;
  790.  
  791.       DialogTHndl = ^DialogTPtr;
  792.       DialogTPtr = ^DialogTemplate;
  793.       DialogTemplate = RECORD
  794.                          boundsRect: Rect;
  795.                          procID: INTEGER;
  796.                          visible: BOOLEAN;
  797.                          filler1: BOOLEAN;
  798.                          goAwayFlag: BOOLEAN;
  799.                          filler2: BOOLEAN;
  800.                          refCon: LongInt;
  801.                          ItemsID: INTEGER;
  802.                          title: STR255;
  803.                        END;
  804.  
  805.       StageList = PACKED RECORD
  806.                     boldItm4: 0..1;
  807.                     boxDrwn4: BOOLEAN;
  808.                     sound4: 0..3;
  809.                     boldItm3: 0..1;
  810.                     boxDrwn3: BOOLEAN;
  811.                     sound3: 0..3;
  812.                     boldItm2: 0..1;
  813.                     boxDrwn2: BOOLEAN;
  814.                     sound2: 0..3;
  815.                     boldItm1: 0..1;
  816.                     boxDrwn1: BOOLEAN;
  817.                     sound1: 0..3;
  818.                   END;
  819.  
  820.       AlertTHndl = ^AlertTPtr;
  821.       AlertTPtr = ^AlertTemplate;
  822.       AlertTemplate = RECORD
  823.                         boundsRect: Rect;
  824.                         ItemsID: INTEGER;
  825.                         stages: StageList;
  826.                       END;
  827.  
  828. \ ,138
  829. 138
  830. Desk Manager Definitions.
  831.  
  832. CONST (Assembly-Language)
  833.  
  834. drvrFlags       EQU  $0     ; various flags and permissions [word]
  835. drvrDelay       EQU  $2     ; # of ticks between systask calls [word]
  836. drvrEMask       EQU  $4     ; event mask [word]
  837. drvrMenu        EQU  $6     ; driver menu ID [word]
  838. drvrOpen        EQU  $8     ; open routine offset [word]
  839. drvrPrime       EQU  $A     ; prime routine offset [word]
  840. drvrCtl         EQU  $C     ; control routine offset [word]
  841. drvrStatus      EQU  $E     ; status routine offset [word]
  842. drvrClose       EQU  $10    ; warmstart reset routine offset [word]
  843. drvrName        EQU  $12    ; length byte and name of driver [string]
  844.  
  845. accEvent        EQU  $40    ; event message from SystemEvent
  846. accRun          EQU  $41    ; run message from SystemTask
  847. accCursor       EQU  $42    ; cursor message from SystemTask
  848. accMenu         EQU  $43    ; menu message from SystemMenu
  849. accUndo         EQU  $44    ; undo message from SystemEdit
  850. accCut          EQU  $46    ; cut message from SystemEdit
  851. accCopy         EQU  $47    ; copy message from SystemEdit
  852. accPaste        EQU  $48    ; paste message from SystemEdit
  853. accClear        EQU  $49    ; clear message from SystemEdit
  854.  
  855. goodBye         EQU  -1     ; goodbye message
  856.  
  857. \ ,139
  858. 139
  859. Scrap Manager Definitions.
  860.  
  861. CONST
  862.       noScrapErr    = - 100; {desk scrap isn't initialized}
  863.       noTypeErr     = - 102;
  864.  
  865. TYPE
  866.       ScrapStuff = RECORD
  867.                      scrapSize: LongInt;
  868.                      scrapHandle: Handle;
  869.                      scrapCount: INTEGER;
  870.                      scrapState: INTEGER;
  871.                      scrapName: StringPtr;
  872.                    END;
  873.       pScrapStuff = ^ScrapStuff;
  874.  
  875. \ ,140
  876. 140
  877. Toolbox Utilities Definitions.
  878.  
  879. CONST
  880.       sysPatListID  = 0;    {ID of PAT# which contains 38 patterns}
  881.  
  882.       iBeamCursor   = 1;    {text selection cursor}
  883.       crossCursor   = 2;    {for drawing graphics}
  884.       plusCursor    = 3;    {for structured selection}
  885.       watchCursor   = 4;    {for indicating a long delay}
  886.  
  887. TYPE
  888.       Int64Bit = RECORD
  889.                    hiLong: LongInt;
  890.                    loLong: LongInt;
  891.                  END;
  892.  
  893.       CursPtr = ^Cursor;
  894.       CursHandle = ^CursPtr;
  895.  
  896.       PatPtr = ^Pattern;
  897.       PatHandle = ^PatPtr;
  898.  
  899. \ ,141
  900. 141
  901. Package Manager Definitions.
  902.  
  903. CONST
  904.       listMgr   = 0; {list manager}
  905.       dskInit   = 2; {Disk Initializaton}
  906.       stdFile   = 3; {Standard File}
  907.       flPoint   = 4; {Floating-Point Arithmetic}
  908.       trFunc    = 5; {Transcendental Functions}
  909.       intUtil   = 6; {International Utilities}
  910.       bdConv    = 7; {Binary/Decimal Conversion}
  911.  
  912.          putDlgID = - 3999; {SFPutFile dialog template ID}
  913.  
  914.                         putSave = 1;                         {save button}
  915.                         putCancel = 2;                 {cancel button}
  916.                         putEject = 5;                     {eject button}
  917.                         putDrive = 6;                     {drive button}
  918.                         putName = 7;                         {editTExt item for file name}
  919.             
  920.                         getDlgID = - 4000; {SFGetFile dialog template ID}
  921.             
  922.                         getOpen = 1;                         {open button}
  923.                         getCancel = 3;     {cancel button}
  924.                         getEject = 5;      {eject button}
  925.                         getDrive = 6;      {drive button}
  926.                         getNmList = 7;     {userItem for file name list}
  927.                         getScroll = 8;     {userItem for scroll bar}
  928.  
  929.     TYPE
  930.  
  931.       SFReply = RECORD
  932.                                                             good: BOOLEAN;     {ignore command if FALSE}
  933.                                                             copy: BOOLEAN;     {not used}
  934.                                                             fType: OsType;     {file type or not used}
  935.                                                             vRefNum: INTEGER;  {volume reference number}
  936.                                                             version: INTEGER;  {file's version number}
  937.                                                             fName: String[63]; {file name}
  938.                                                     END;                 {SFReply}
  939.  
  940.       SFTypeList = ARRAY [0..3] OF OsType;
  941.  
  942. \ ,142
  943. 142
  944. Memory Manager Definition.
  945.  
  946. CONST
  947.   MemFullErr    = - 108; { Not enough room in heap zone }
  948.   NilHandleErr  = - 109; { Master Pointer was NIL in HandleZone or other }
  949.   MemWZErr      = - 111; { WhichZone failed (applied to free block) }
  950.   MemPurErr     = - 112; { trying to purge a locked or non-purgeable block }
  951.   MemLockedErr  = - 117; { Block is locked }
  952.   NoErr         = 0;     { All is well }
  953.  
  954. TYPE
  955.       SignedByte    = - 128..127;   { any byte in memory }
  956.       Byte          = 0..255;       { unsigned byte for fontmgr }
  957.       Ptr           = ^SignedByte;  { blind pointer }
  958.       Handle        = ^Ptr;         { pointer to a master pointer }
  959.       ProcPtr       = Ptr;          { pointer to a procedure }
  960.       Fixed         = LongInt;      { fixed point arithmetic type }
  961.  
  962.       Str255        = String[255];  { maximum string size }
  963.       StringPtr     = ^Str255;      { pointer to maximum string }
  964.       StringHandle  = ^StringPtr;   { handle to maximum string }
  965.  
  966.       Zone = RECORD
  967.                BkLim: Ptr;
  968.                PurgePtr: Ptr;
  969.                HFstFree: Ptr;
  970.                ZCBFree: LongInt;
  971.                GZProc: ProcPtr;
  972.                MoreMast: INTEGER;
  973.                Flags: INTEGER;
  974.                CntRel: INTEGER;
  975.                MaxRel: INTEGER;
  976.                CntNRel: INTEGER;
  977.                MaxNRel: INTEGER;
  978.                CntEmpty: INTEGER;
  979.                CntHandles: INTEGER;
  980.                MinCBFree: LongInt;
  981.                PurgeProc: ProcPtr;
  982.                SparePtr: Ptr;       { reserved for future }
  983.                AllocPtr: Ptr;
  984.                HeapData: INTEGER;
  985.              END;
  986.       THz   = ^Zone;    { pointer to the start of a heap zone }
  987.       Size  = LongInt;  { size of a block in bytes }
  988.       OSErr = INTEGER;  { error code }
  989.  
  990.       QElemPtr = ^QElem; {ptr to generic queue element}
  991.  
  992. \ ,143
  993. 143
  994. Segment Loader Definitions.
  995.  
  996. CONST
  997.       appOpen  = 0 ;  { Open the Document (s) }
  998.       appPrint = 1 ;  { Print the Document (s)}
  999. TYPE
  1000.       appFile = RECORD
  1001.                   vRefNum: INTEGER;
  1002.                   ftype: OSType;
  1003.                   versNum: INTEGER; {versNum in high byte}
  1004.                   fName: str255;
  1005.                 END; {appFile}
  1006.  
  1007. \ ,144
  1008. 144
  1009. OS Event Definitions.
  1010.  
  1011. CONST
  1012.       NullEvent     = 0;
  1013.       mouseDown     = 1;
  1014.       mouseUp       = 2;
  1015.       keyDown       = 3;
  1016.       keyUp         = 4;
  1017.       autoKey       = 5;
  1018.       updateEvt     = 6;
  1019.       diskEvt       = 7;
  1020.       activateEvt   = 8;
  1021.       networkEvt    = 10;
  1022.       driverEvt     = 11;
  1023.       app1Evt       = 12;
  1024.       app2Evt       = 13;
  1025.       app3Evt       = 14;
  1026.       app4Evt       = 15;
  1027.  
  1028.       { event mask equates }
  1029.       mDownMask     = 2;
  1030.       mUpMask       = 4;
  1031.       keyDownMask   = 8;
  1032.       keyUpMask     = 16;
  1033.       autoKeyMask   = 32;
  1034.       updateMask    = 64;
  1035.       diskMask      = 128;
  1036.       activMask     = 256;
  1037.       networkMask   = 1024;
  1038.       driverMask    = 2048;
  1039.       app1Mask      = 4096;
  1040.       app2Mask      = 8192;
  1041.       app3Mask      = 16384;
  1042.       app4Mask      = - 32768;
  1043.  
  1044.       {to decipher event message for keyDown events}
  1045.       charCodeMask  = $000000FF;
  1046.       keyCodeMask   = $0000FF00;
  1047.  
  1048.       { modifiers }
  1049.       optionKey     = 2048; { Bit 3 of high byte }
  1050.       alphaLock     = 1024; { Bit 2 }
  1051.       ShiftKey      = 512;  { Bit 1 }
  1052.       CmdKey        = 256;  { Bit 0 }
  1053.       BtnState      = 128;  { Bit 7 of low byte is mouse button state }
  1054.  
  1055.       activeFlag    = 1;    { bit 0 of modifiers for activate event }
  1056.  
  1057.       {error for PostEvent}
  1058.       EvtNotEnb     = 1;
  1059.  
  1060. TYPE
  1061.       EventRecord = RECORD
  1062.                       what: INTEGER;
  1063.                       message: LongInt;
  1064.                       when: LongInt;
  1065.                       where: Point;
  1066.                       modifiers: INTEGER;
  1067.                     END;
  1068.  
  1069.       evQEl = RECORD
  1070.                 qLink: QElemPtr;
  1071.                 qType: INTEGER;
  1072.                 evtQwhat: INTEGER; {this part is identical to the EventRecord
  1073.                                     as...}
  1074.                 evtQmessage: LongInt; {defined in ToolIntf}
  1075.                 evtQwhen: LongInt;
  1076.                 evtQwhere: Point;
  1077.                 evtQmodifiers: INTEGER;
  1078.               END;
  1079.  
  1080. \ ,145
  1081. 145
  1082. File Manager Definitions.
  1083.  
  1084. CONST
  1085.   DirFulErr     = - 33; { Directory full }
  1086.   DskFulErr     = - 34; { disk full }
  1087.   NSVErr        = - 35; { no such volume }
  1088.   IOErr         = - 36; { I/O error }
  1089.   BdNamErr      = - 37; { bad name }
  1090.   FNOpnErr      = - 38; { File not open }
  1091.   EOFErr        = - 39; { End of file }
  1092.   PosErr        = - 40; { tried to position to before start of file (r/w) }
  1093.   MFulErr       = - 41; { memory full(open) or file won't fit (load) }
  1094.   TMFOErr       = - 42; { too many files open }
  1095.   FNFErr        = - 43; { File not found }
  1096.  
  1097.   WPrErr        = - 44; { diskette is write protected }
  1098.   FLckdErr      = - 45; { file is locked }
  1099.   VLckdErr      = - 46; { volume is locked }
  1100.   FBsyErr       = - 47; { File is busy (delete) }
  1101.   DupFNErr      = - 48; { duplicate filename (rename) }
  1102.   OpWrErr       = - 49; { file already open with with write permission }
  1103.   ParamErr      = - 50; { error in user parameter list }
  1104.   RFNumErr      = - 51; { refnum error }
  1105.   GFPErr        = - 52; { get file position error }
  1106.   VolOffLinErr  = - 53; { volume not on line error (was Ejected) }
  1107.   PermErr       = - 54; { permissions error (on file open) }
  1108.   VolOnLinErr   = - 55; { drive volume already on-line at MountVol }
  1109.   NSDrvErr      = - 56; { no such drive (tried to mount a bad drive num) }
  1110.   NoMacDskErr   = - 57; { not a mac diskette (sig bytes are wrong) }
  1111.   ExtFSErr      = - 58; { volume in question belongs to an external fs }
  1112.   FSRnErr       = - 59; { file system rename error }
  1113.   BadMDBErr     = - 60; { bad master directory block }
  1114.   WrPermErr     = - 61; { write permissions error }
  1115.  
  1116.   lastDskErr    = - 64; { last in a range of disk errors }
  1117.   noDriveErr    = - 64; { drive not installed }
  1118.   offLinErr     = - 65; { r/w requested for an off-line drive }
  1119.   noNybErr      = - 66; { couldn't find 5 nybbles in 200 tries }
  1120.   noAdrMkErr    = - 67; { couldn't find valid addr mark }
  1121.   dataVerErr    = - 68; { read verify compare failed }
  1122.   badCkSmErr    = - 69; { addr mark checksum didn't check }
  1123.   badBtSlpErr   = - 70; { bad addr mark bit slip nibbles }
  1124.   noDtaMkErr    = - 71; { couldn't find a data mark header }
  1125.   badDCkSum     = - 72; { bad data mark checksum }
  1126.   badDBtSlp     = - 73; { bad data mark bit slip nibbles }
  1127.   wrUnderRun    = - 74; { write underrun occurred }
  1128.   cantStepErr   = - 75; { step handshake failed }
  1129.   tk0BadErr     = - 76; { track 0 detect doesn't change }
  1130.   initIWMErr    = - 77; { unable to initialize IWM }
  1131.   twoSideErr    = - 78; { tried to read 2nd side on a 1-sided drive }
  1132.   spdAdjErr     = - 79; { unable to correctly adjust disk speed }
  1133.   seekErr       = - 80; { track number wrong on address mark }
  1134.   sectNFErr     = - 81; { sector number never found on a track }
  1135.   firstDskErr   = - 84; { first in a range of disk errors }
  1136.  
  1137.   DirNFErr      = - 120; { Directory not found }
  1138.   TMWDOErr      = - 121; { No free WDCB available }
  1139.   BadMovErr     = - 122; { Move into offspring error }
  1140.   WrgVolTypErr  = - 123; { Wrong volume type error - operation not
  1141.                             supported for MFS}
  1142.   FSDSIntErr    = - 127; { Internal file system error }
  1143.  
  1144.   MaxSize       = $800000; { Max data block size is 8 megabytes }
  1145.  
  1146.       {finder constants}
  1147.       fOnDesk       = 1;
  1148.       fHasBundle    = 8192;
  1149.       fInvisible    = 16384;
  1150.       fTrash        = - 3;
  1151.       fDesktop      = - 2;
  1152.       fDisk         = 0;
  1153.  
  1154.       {io constants}
  1155.  
  1156.       {ioPosMode values}
  1157.       fsAtMark      = 0;
  1158.       fsFromStart   = 1;
  1159.       fsFromLEOF    = 2;
  1160.       fsFromMark    = 3;
  1161.       rdVerify      = 64;
  1162.  
  1163.       {ioPermission values}
  1164.       fsCurPerm     = 0;
  1165.       fsRdPerm      = 1;
  1166.       fsWrPerm      = 2;
  1167.       fsRdWrPerm    = 3;
  1168.       fsRdWrShPerm  = 4;
  1169.  
  1170. TYPE
  1171.   ParamBlkType = (IOParam, FileParam, VolumeParam, CntrlParam);
  1172.  
  1173.   OSType = PACKED ARRAY [1..4] OF CHAR; {same as rsrc mgr's Restype}
  1174.  
  1175.   FInfo = RECORD                {record of finder info}
  1176.             fdType: OSType;     {the type of the file}
  1177.             fdCreator: OSType;  {file's creator}
  1178.             fdFlags: INTEGER;   {flags ex. hasbundle,invisible,locked,
  1179.                                     etc.}
  1180.             fdLocation: Point;  {file's location in folder}
  1181.             fdFldr: INTEGER;    {folder containing file}
  1182.           END; {FInfo}
  1183.  
  1184.  
  1185.   FXInfo = RECORD
  1186.              fdIconID: INTEGER;         {Icon ID}
  1187.              fdUnused: ARRAY [1..4] OF INTEGER; {unused but reserved 8 bytes}
  1188.              fdComment: INTEGER;        {Comment ID}
  1189.              fdPutAway: LongInt;        {Home Dir ID}
  1190.            END;
  1191.  
  1192.   DInfo = RECORD
  1193.             frRect: Rect;       {folder rect}
  1194.             frFlags: INTEGER;   {Flags}
  1195.             frLocation: Point;  {folder location}
  1196.             frView: INTEGER;    {folder view}
  1197.           END;
  1198.  
  1199.   DXInfo = RECORD
  1200.              frScroll: Point;       {scroll position}
  1201.              frOpenChain: LongInt;  {DirID chain of open folders}
  1202.              frUnused: INTEGER;     {unused but reserved}
  1203.              frComment: INTEGER;    {comment}
  1204.              frPutAway: LongInt;    {DirID}
  1205.            END;
  1206.  
  1207.  
  1208.   ParamBlockRec = RECORD
  1209.   {12 byte header used by the file and IO system}
  1210.     qLink: QElemPtr;        {queue link in header}
  1211.     qType: INTEGER;         {type byte for safety check}
  1212.     ioTrap: INTEGER;        {FS: the Trap}
  1213.     ioCmdAddr: Ptr;         {FS: address to dispatch to}
  1214.  
  1215.              {common header to all variants}
  1216.     ioCompletion: ProcPtr; {completion routine addr (0 for
  1217.                             synch calls)}
  1218.     ioResult: OSErr;        {result code}
  1219.     ioNamePtr: StringPtr;   {ptr to Vol:FileName string}
  1220.     ioVRefNum: INTEGER;     {volume refnum (DrvNum for Eject and
  1221.                                 MountVol)}
  1222.  
  1223. {different components for the different type of parameter blocks}
  1224.     CASE ParamBlkType OF
  1225.       IOParam:
  1226.         (ioRefNum: INTEGER;     {refNum for I/O operation}
  1227.          ioVersNum: SignedByte; {version number}
  1228.          ioPermssn: SignedByte; {Open: permissions (byte)}
  1229.  
  1230.          ioMisc: Ptr;           {Rename: new name}
  1231.                                 {GetEOF,SetEOF: logical end of file}
  1232.                                 {Open: optional ptr to buffer}
  1233.                                 {SetFileType: new type}
  1234.          ioBuffer: Ptr;         {data buffer Ptr}
  1235.          ioReqCount: LongInt;   {requested byte count; also =
  1236.                                  ioNewDirID}
  1237.          ioActCount: LongInt;   {actual byte count completed}
  1238.          ioPosMode: INTEGER;    {initial file positioning}
  1239.          ioPosOffset: LongInt); {file position offset}
  1240.  
  1241.       FileParam:
  1242.         (ioFRefNum: INTEGER;        {reference number}
  1243.          ioFVersNum: SignedByte;    {version number}
  1244.          filler1: SignedByte;
  1245.          ioFDirIndex: INTEGER;      {GetFInfo directory index}
  1246.          ioFlAttrib: SignedByte;    {GetFInfo: in-use bit=7, lock
  1247.                                         bit=0}
  1248.          ioFlVersNum: SignedByte;   {file version number}
  1249.          ioFlFndrInfo: FInfo;       {user info}
  1250.          ioFlNum: LongInt;          {GetFInfo: file number; TF-
  1251.                                         ioDirID}
  1252.          ioFlStBlk: INTEGER;        {start file block (0 if none)}
  1253.          ioFlLgLen: LongInt;        {logical length (EOF)}
  1254.          ioFlPyLen: LongInt;        {physical lenght}
  1255.          ioFlRStBlk: INTEGER;       {start block rsrc fork}
  1256.          ioFlRLgLen: LongInt;       {file logical length rsrc fork}
  1257.          ioFlRPyLen: LongInt;       {file physical length rsrc fork}
  1258.          ioFlCrDat: LongInt;        {file creation date & time (32
  1259.                                         bits in secs)}
  1260.          ioFlMdDat: LongInt);       {last modified date and time}
  1261.  
  1262.       VolumeParam:
  1263.         (filler2: LongInt;
  1264.          ioVolIndex: INTEGER;   {volume index number}
  1265.          ioVCrDate: LongInt;    {creation date and time}
  1266.          ioVLsBkUp: LongInt;    {last backup date and time}
  1267.          ioVAtrb: INTEGER;      {volume attrib}
  1268.          ioVNmFls: INTEGER;     {number of files in directory}
  1269.          ioVDirSt: INTEGER;     {start block of file directory}
  1270.          ioVBlLn: INTEGER;      {GetVolInfo: length of dir in
  1271.                                     blocks}
  1272.          ioVNmAlBlks: INTEGER;  {GetVolInfo: num blks (of alloc
  1273.                                     size)}
  1274.          ioVAlBlkSiz: LongInt;  {GetVolInfo: alloc blk byte
  1275.                                     size}
  1276.          ioVClpSiz: LongInt;    {GetVolInfo: bytes to allocate at
  1277.                                     a time}
  1278.          ioAlBlSt: INTEGER;     {starting disk(512-byte) block in
  1279.                                     block map}
  1280.          ioVNxtFNum: LongInt;   {GetVolInfo: next free file
  1281.                                     number}
  1282.          ioVFrBlk: INTEGER);    {GetVolInfo: # free alloc blks
  1283.                                     for this vol}
  1284.  
  1285.       CntrlParam:
  1286.         (ioCRefNum: INTEGER;        {refNum for I/O operation}
  1287.          CSCode: INTEGER;           {word for control status code}
  1288.          CSParam: ARRAY [0..10] OF INTEGER); {operation-defined
  1289.                                                 parameters}
  1290.   END; {ParamBlockRec}
  1291.  
  1292.   ParmBlkPtr = ^ParamBlockRec;
  1293.  
  1294. \ ,146
  1295. 146
  1296. Printing Manager Definitions.
  1297.  
  1298. CONST
  1299.   iPrPgFract = 120; {Page scale factor. ptPgSize (below) is in units of
  1300.                      1/iPrPgFract }
  1301.  
  1302.   iPrPgFst      = 1; {Page range constants}
  1303.   iPrPgMax      = 9999;
  1304.  
  1305.   iPrRelease    = 3; {Current version number of the code.} {DC 7/23/84}
  1306.   iPfMaxPgs     = 128; {Max number of pages in a print file.}
  1307.  
  1308.   {Driver constants}
  1309.   iPrBitsCtl    = 4; {The Bitmap Print Proc's ctl number}
  1310.   lScreenBits   = $00000000; {The Bitmap Print Proc's Screen Bitmap
  1311.                                 param}
  1312.   lPaintBits    = $00000001; {The Bitmap Print Proc's Paint [sq pix]
  1313.                                 param}
  1314.   lHiScreenBits = $00000010; {The Bitmap Print Proc's Screen Bitmap
  1315.                                 param}
  1316.   lHiPaintBits  = $00000011; {The Bitmap Print Proc's Paint [sq pix]
  1317.                                 param}
  1318.   iPrIOCtl      = 5; {The Raw Byte IO Proc's ctl number}
  1319.   iPrEvtCtl     = 6; {The PrEvent Proc's ctl number}
  1320.   lPrEvtAll     = $0002FFFD; {The PrEvent Proc's CParam for the entire
  1321.                                 screen}
  1322.   lPrEvtTop     = $0001FFFD; {The PrEvent Proc's CParam for the top
  1323.                                 folder}
  1324.   iPrDevCtl     = 7;         {The PrDevCtl Proc's ctl number}
  1325.   lPrReset      = $00010000; {The PrDevCtl Proc's CParam for reset}
  1326.   lPrPageEnd    = $00020000; {The PrDevCtl Proc's CParam for end page}
  1327.   lPrLineFeed   = $00030000; {The PrDevCtl Proc's CParam for paper
  1328.                                 advance}
  1329.   lPrLFSixth    = $0003FFFF; {The PrDevCtl Proc's CParam for 1/6 th inch
  1330.                                 paper advance}
  1331.   lPrLFEighth   = $0003FFFE; {The PrDevCtl Proc's CParam for 1/8 th inch
  1332.                                 paper advance}
  1333.   iFMgrCtl      = 8;         {The FMgr's Tail-hook Proc's ctl number}
  1334.   { [The Pre-Hook is the status call] }
  1335.  
  1336.   {Error Constants:}
  1337.   iMemFullErr   = - 108;
  1338.   iPrAbort      = 128;
  1339.   iIOAbort      = - 27;
  1340.  
  1341.   {The PrVars lo mem area:}
  1342.   pPrGlobals    = $00000944;
  1343.   bDraftLoop    = 0;
  1344.   bSpoolLoop    = 1;
  1345.   bUser1Loop    = 2;
  1346.   bUser2Loop    = 3;
  1347.  
  1348.   {The Currently supported printers:}
  1349.   bDevCItoh     = 1;
  1350.   iDevCItoh     = $0100; {CItoh}
  1351.   bDevDaisy     = 2;
  1352.   iDevDaisy     = $0200; {Daisy}
  1353.   bDevLaser     = 3;
  1354.   iDevLaser     = $0300; {Laser}
  1355.  
  1356. TYPE
  1357.   TPRect = ^Rect;       {A Rect Ptr}
  1358.   TPBitMap = ^BitMap;   {A BitMap Ptr}
  1359.  
  1360.   {NOTE: Changes will also affect: PrEqu, TCiVars & TPfVars}
  1361.   TPrVars = RECORD {4 longs for printing, see SysEqu for location.}
  1362.               iPrErr: Integer; {Current print error. Set to iPrAbort to
  1363.                                     abort printing.}
  1364.               bDocLoop: SignedByte; {The Doc style: Draft, Spool, ..,
  1365.                                     and .. Currently use low 2 bits; the
  1366.                                     upper 6 are for flags.}
  1367.               bUser1: SignedByte; {Spares used by the print code}
  1368.               lUser1: LongInt;
  1369.               lUser2: LongInt;
  1370.               lUser3: LongInt;
  1371.             END;
  1372.   TPPrVars = ^TPrVars;
  1373.  
  1374.   TPrInfo = RECORD {Print Info Record: The parameters needed for page
  1375.                     composition.}
  1376.               iDev: Integer; {Font mgr/QuickDraw device code}
  1377.               iVRes: Integer; {Resolution of device, in device
  1378.                                 coordinates}
  1379.               iHRes: Integer; { ..note: V before H => compatable with
  1380.                                 Point.}
  1381.               rPage: Rect; {The page (printable) rectangle in device
  1382.                             coordinates.}
  1383.             END;
  1384.   TPPrInfo = ^TPrInfo;
  1385.  
  1386.   {These are types of paper feeders.}
  1387.   TFeed = (feedCut, feedFanfold, feedMechCut, feedOther);
  1388.  
  1389.   TPrStl = RECORD {Printer Style: The printer configuration and usage
  1390.                    information.}
  1391.              wDev: Integer; {The device (driver) number. Hi byte=RefNum,
  1392.                                 Lo byte=variant. f0 = fHiRes,
  1393.                                 f1 = fPortrait, f2 = fSqPix,
  1394.                                 f3 = f2xZoom, f4 = fScroll.}
  1395.              iPageV: Integer; {paper size in units of 1/iPrPgFract}
  1396.              iPageH: Integer; { ..note: V before H => compatable with
  1397.                                 Point.}
  1398.              bPort: SignedByte; {The IO port number. Refnum?}
  1399.              feed: TFeed; {paper feeder type.}
  1400.            END;
  1401.   TPPrStl = ^TPrStl;
  1402.  
  1403.   {Banding data structures. Not of general interest to Apps.}
  1404.   TScan = {Band Scan direction Top-Bottom, Left-Right, etc.}
  1405.   (scanTB, scanBT, scanLR, scanRL);
  1406.  
  1407.   TPrXInfo = RECORD {The print time eXtra information.}
  1408.                iRowBytes: Integer; {The Band's rowBytes.}
  1409.                iBandV: Integer; {Size of band, in device coordinates}
  1410.                iBandH: Integer; { ..note: V before H => compatible with
  1411.                                  Point.}
  1412.                iDevBytes: Integer; {Size for allocation. May be more
  1413.                                     than rBounds size!}
  1414.                iBands: Integer; {Number of bands per page.}
  1415.  
  1416.                bPatScale: SignedByte; {Pattern scaling}
  1417.                bULThick: SignedByte; {3 Underscoring parameters}
  1418.                bULOffset: SignedByte;
  1419.                bULShadow: SignedByte;
  1420.  
  1421.                scan: TScan; {Band scan direction}
  1422.                bXInfoX: SignedByte; {An eXtra byte.}
  1423.              END;
  1424.   TPPrXInfo = ^TPrXInfo;
  1425.  
  1426.   TPrJob = RECORD {Print Job: Print "form" for a single print request.}
  1427.              iFstPage: Integer; {Page Range.}
  1428.              iLstPage: Integer;
  1429.              iCopies: Integer; {No. copies.}
  1430.              bJDocLoop: SignedByte; {The Doc style: Draft, Spool, ..,
  1431.                                         and ..}
  1432.              fFromUsr: Boolean; {Printing from an User's App (not PrApp)
  1433.                                     flag}
  1434.              pIdleProc: ProcPtr; {The Proc called while waiting on IO
  1435.                                     etc.}
  1436.              pFileName: StringPtr; {Spool File Name: NIL for default.}
  1437.              iFileVol: Integer; {Spool File vol, set to 0 initially}
  1438.              bFileVers: SignedByte; {Spool File version, set to 0
  1439.                                         initially}
  1440.              bJobX: SignedByte; {An eXtra byte.}
  1441.            END;
  1442.   TPPrJob = ^TPrJob;
  1443.  
  1444.   TPrint = RECORD {The universal 120 byte printing record}
  1445.              iPrVersion: Integer; {2} {Printing software version}
  1446.              PrInfo: TPrInfo; {14} {the PrInfo data associated with the
  1447.                                     current style.}
  1448.              rPaper: Rect; {8} {The paper rectangle [offset from rPage]}
  1449.              PrStl: TPrStl; {8} {This print request's style.}
  1450.              PrInfoPT: TPrInfo; {14} {Print Time Imaging metrics}
  1451.              PrXInfo: TPrXInfo; {16} {Print-time (expanded) Print info
  1452.                                       record.}
  1453.              PrJob: TPrJob; {20} {The Print Job request}
  1454.                   {82} {Total of the above; 120-82 = 38 bytes needed to
  1455.                         fill 120}
  1456.              PrintX: ARRAY [1..19] OF Integer; {Spare to fill to 120
  1457.                                                 bytes!}
  1458.            END;
  1459.   TPPrint = ^TPrint;
  1460.   THPrint = ^TPPrint;
  1461.  
  1462. {Printing Graf Port. All printer imaging, whether spooling, banding, etc, happens "thru" a GrafPort.}
  1463.   TPrPort = RECORD {This is the "PrPeek" record.}
  1464.               GPort: GrafPort; {The Printer's graf port.}
  1465.               GProcs: QDProcs; {..and its procs}
  1466.  
  1467.               lGParam1: LongInt; {16 bytes for private parameter storage.}
  1468.               lGParam2: LongInt;
  1469.               lGParam3: LongInt;
  1470.               lGParam4: LongInt;
  1471.  
  1472.               fOurPtr: Boolean; {Whether the PrPort allocation was done by
  1473.                                  us.}
  1474.               fOurBits: Boolean; {Whether the BitMap allocation was done by
  1475.                                   us.}
  1476.             END;
  1477.   TPPrPort = ^TPrPort;
  1478.  
  1479.   TPrStatus = RECORD {Print Status: Print information during printing.}
  1480.                 iTotPages: Integer; {Total pages in Print File.}
  1481.                 iCurPage: Integer; {Current page number}
  1482.                 iTotCopies: Integer; {Total copies requested}
  1483.                 iCurCopy: Integer; {Current copy number}
  1484.                 iTotBands: Integer; {Total bands per page.}
  1485.                 iCurBand: Integer; {Current band number}
  1486.                 fPgDirty: Boolean; {True if current page has been written to.}
  1487.                 fImaging: Boolean; {Set while in band's DrawPic call.}
  1488.                 hPrint: THPrint; {Handle to the active Printer record}
  1489.                 pPrPort: TPPrPort; {Ptr to the active PrPort}
  1490.                 hPic: PicHandle; {Handle to the active Picture}
  1491.               END;
  1492.   TPPrStatus = ^TPrStatus;
  1493.  
  1494. {PicFile = a TPfHeader followed by n QuickDraw Pics (whose PicSize is invalid!)}
  1495.   TPfPgDir = RECORD
  1496.                iPages: Integer;
  1497.                lPgPos: ARRAY [0..iPfMaxPgs] OF LongInt;
  1498.              END;
  1499.   TPPfPgDir = ^TPfPgDir;
  1500.   THPfPgDir = ^TPPfPgDir;
  1501.  
  1502.   TPfHeader = RECORD {Print File header.}
  1503.                 Print: TPrint;
  1504.                 PfPgDir: TPfPgDir;
  1505.               END;
  1506.   TPPfHeader = ^TPfHeader;
  1507.   THPfHeader = ^TPPfHeader; {Note: Type compatable with an hPrint.}
  1508.  
  1509. { This is the Printing Dialog Record. Only used by folks appending their own dialogs. }
  1510.   TPrDlg = RECORD {Print Dialog: The Dialog Stream object.}
  1511.              Dlg: DialogRecord; {The Dialog window}
  1512.              pFltrProc: ProcPtr; {The Filter Proc.}
  1513.              pItemProc: ProcPtr; {The Item evaluating proc.}
  1514.              hPrintUsr: THPrint; {The user's print record.}
  1515.              fDoIt: Boolean;
  1516.              fDone: Boolean;
  1517.              lUser1: LongInt; {Four longs for user's to hang global data.}
  1518.              lUser2: LongInt;
  1519.              lUser3: LongInt;
  1520.              lUser4: LongInt;
  1521.               {  ...Plus more stuff needed by the particular printing dialog.}
  1522.            END;
  1523.   TPPrDlg = ^TPrDlg; {== a dialog ptr}
  1524. \ ,147
  1525. 147
  1526. Device Manager Definitions.
  1527.  
  1528. \ ,148
  1529. 148
  1530. Disk Driver Definitions.
  1531.  
  1532. \ ,149
  1533. 149
  1534. Sound Driver Definitions.
  1535. \ ,151
  1536. 151
  1537. AppleTalk definitions.
  1538.  
  1539. CONST
  1540.  
  1541.         lapSize = 20;
  1542.         ddpSize = 26;
  1543.         nbpSize = 26;
  1544.         atpSize = 56;
  1545.  
  1546.         {error codes}
  1547.  
  1548.         ddpSktErr = - 91;
  1549.         ddpLenErr = - 92;
  1550.         noBridgeErr = - 93;
  1551.         LAPProtErr = - 94;
  1552.         excessCollsns = - 95;
  1553.  
  1554.         nbpBuffOvr = - 1024;
  1555.         nbpNoConfirm = - 1025;
  1556.         nbpConfDiff = - 1026;
  1557.         nbpDuplicate = - 1027;
  1558.         nbpNotFound = - 1028;
  1559.         nbpNISErr = - 1029;
  1560.  
  1561.         reqFailed = - 1096;
  1562.         tooManyReqs = - 1097;
  1563.         tooManySkts = - 1098;
  1564.         badATPSkt = - 1099;
  1565.         badBuffNum = - 1100;
  1566.         noRelErr = - 1101;
  1567.         cbNotFound = - 1102;
  1568.         noSendResp = - 1103;
  1569.         noDataArea = - 1104;
  1570.         reqAborted = - 1105;
  1571.  
  1572.         buf2SmallErr = - 3101;
  1573.         noMPPErr = - 3102;
  1574.         ckSumErr = - 3103;
  1575.         extractErr = - 3104;
  1576.         readQErr = - 3105;
  1577.         atpLenErr = - 3106;
  1578.         atpBadRsp = - 3107;
  1579.         recNotFnd = - 3108;
  1580.         sktClosedErr = - 3109;
  1581.  
  1582. TYPE
  1583.  
  1584.         ABByte = 1..127;
  1585.  
  1586.         STR32 = STRING[32];
  1587.  
  1588.         ABCallType = (tLAPRead, tLAPWrite, tDDPRead, tDDPWrite, tNBPLookUp,
  1589.                 tNBPConfirm, tNBPRegister, tATPSndRequest, tATPGetRequest,
  1590.                 tATPSdRsp, tATPAddRsp, tATPRequest, tATPResponse);
  1591.  
  1592.         ABProtoType = (lapProto, ddpProto, nbpProto, atpProto);
  1593.  
  1594.         LAPAdrBlock = PACKED RECORD
  1595.                         dstNodeID: Byte;
  1596.                         srcNodeID: Byte;
  1597.                         LAPProtType: ABByte;
  1598.                 END;
  1599.  
  1600.         AddrBlock = PACKED RECORD
  1601.                 aNet: INTEGER;
  1602.                 aNode: Byte;
  1603.                 aSocket: Byte;
  1604.                     END;
  1605.  
  1606.         EntityName = RECORD
  1607.                     objStr: STR32;
  1608.                     typeStr: STR32;
  1609.                     zoneStr: STR32;
  1610.                         END;
  1611.  
  1612.         EntityPtr = ^EntityName;
  1613.  
  1614.         RetransType = PACKED RECORD
  1615.                         retransInterval: Byte;
  1616.                         retransCount: Byte;
  1617.                 END;
  1618.  
  1619.         BitMapType = PACKED ARRAY [0..7] OF BOOLEAN;
  1620.  
  1621.         BDSElement = RECORD
  1622.                     BuffSize: INTEGER;
  1623.                     BuffPtr: Ptr;
  1624.                     DataSize: INTEGER;
  1625.                     UserBytes: LongInt;
  1626.                         END;
  1627.  
  1628.         BDSType = ARRAY [0..7] OF BDSElement;
  1629.  
  1630.         BDSPtr = ^BDSType;
  1631.  
  1632.         ABusRecord = RECORD
  1633.                     abOpCode: ABCallType;
  1634.                     abResult: INTEGER;
  1635.                     abUserReference: LongInt;
  1636.  
  1637.                     CASE ABProtoType OF
  1638.                             lapProto:
  1639.                         (lapAddress: LAPAdrBlock;
  1640.                             lapReqCount: INTEGER;
  1641.                             lapActCount: INTEGER;
  1642.                             lapDataPtr: Ptr; );
  1643.  
  1644.                             ddpProto:
  1645.                         (ddpType: Byte;
  1646.                             ddpSocket: Byte;
  1647.                             ddpAddress: AddrBlock;
  1648.                             ddpReqCount: INTEGER;
  1649.                             ddpActCount: INTEGER;
  1650.                             ddpDataPtr: Ptr;
  1651.                             ddpNodeID: Byte; );
  1652.  
  1653.                             nbpProto:
  1654.                         (nbpEntityPtr: EntityPtr;
  1655.                             nbpBufPtr: Ptr;
  1656.                             nbpBufSize: INTEGER;
  1657.                             nbpDataField: INTEGER;
  1658.                             nbpAddress: AddrBlock;
  1659.                             nbpRetransmitInfo: RetransType; );
  1660.  
  1661.                             atpProto:
  1662.  
  1663.                         (atpSocket: Byte;
  1664.                             atpAddress: AddrBlock;
  1665.                             atpReqCount: INTEGER;
  1666.                             atpDataPtr: Ptr;
  1667.                             atpRspBDSPtr: BDSPtr;
  1668.                             atpBitMap: BitMapType;
  1669.                             atpTransID: INTEGER;
  1670.                             atpActCount: INTEGER;
  1671.                             atpUserData: LongInt;
  1672.                             atpXO: BOOLEAN;
  1673.                             atpEOM: BOOLEAN;
  1674.                             atpTimeOut: Byte;
  1675.                             atpRetries: Byte;
  1676.                             atpNumBufs: Byte;
  1677.                             atpNumRsp: Byte;
  1678.                             atpBDSSize: Byte;
  1679.  
  1680.                             atpRspUData: LongInt;
  1681.                             atpRspBuf: Ptr;
  1682.                             atpRspSize: INTEGER; );
  1683.  
  1684.                         END; {record}
  1685.  
  1686.         ABRecPtr = ^ABusRecord;
  1687.         ABRecHandle = ^ABRecPtr;
  1688.  
  1689. \ ,154
  1690. 154
  1691. List Manager Definitions.
  1692.  
  1693. CONST
  1694.  
  1695. { Masks for selection flags (selFlags) }
  1696.  
  1697.     LOnlyOne = -128;        { 0 = multiple selections, 1 = one }
  1698.     LExtendDrag = 64;       { 1 = drag select without shift key }
  1699.     LNoDisjoint = 32;       { 1 = turn off selections on click }
  1700.     LNoExtend = 16;         { 1 = don't extend shift selections }
  1701.     LNoRect = 8;            { 1 = don't grow (shift,drag) selection as
  1702.                                 rect }
  1703.     LUseSense = 4;          { 1 = shift should use sense of start cell }
  1704.     LNoNilHilite = 2;       { 1 = don't hilite empty cells }
  1705.  
  1706. { Masks for other flags (listFlags) }
  1707.  
  1708.     LDoVAutoscroll = 2;     { 1 = allow vertical autoscrolling }
  1709.     LDoHAutoscroll = 1;     { 1 = allow horizontal autoscrolling }
  1710.  
  1711. { Messages to list definition procedure }
  1712.  
  1713.     LInitMsg = 0;           { tell drawing routines to init themselves }
  1714.     LDrawMsg = 1;           { draw (and de/select) the indicated data }
  1715.     LHiliteMsg = 2;         { invert hilite state of specified cell }
  1716.     LCloseMsg = 3;          { shut down, the list is being disposed }
  1717.  
  1718. TYPE
  1719.  
  1720.     Cell = Point;
  1721.  
  1722.     dataArray  = PACKED ARRAY[0..32000] OF Char;
  1723.     dataPtr    = ^dataArray;
  1724.     dataHandle = ^dataPtr;
  1725.  
  1726.     ListPtr    = ^ListRec;
  1727.     ListHandle = ^ListPtr;
  1728.     ListRec    = RECORD
  1729.             rView : Rect;               {Rect in which we are viewed}
  1730.             port : GrafPtr;             {Grafport that owns us}
  1731.             indent : Point;             {Indent pixels in cell}
  1732.             cellSize : Point;           {Cell size}
  1733.             visible : Rect;             {visible row/column bounds}
  1734.             vScroll : ControlHandle;    {vertical scroll bar (or NIL)}
  1735.             hScroll : ControlHandle;    {horizontal scroll bar (or NIL)}
  1736.             selFlags : SignedByte;      { defines selection characteristics
  1737.             LActive : Boolean;          { active or not }
  1738.             LReserved : SignedByte;     { internally used flags }
  1739.             listFlags : SignedByte;     { other flags }
  1740.             clikTime : Longint;         { save time of last click }
  1741.             clikLoc : Point;            { save position of last click }
  1742.             mouseLoc : Point;           { current mouse position }
  1743.             LClikLoop : Ptr;            { routine called repeatedly during
  1744.                                         ListClick }
  1745.             lastClick : Cell;           { the last cell clicked in }
  1746.             refCon : Longint;           { reference value }
  1747.             listDefProc : Handle;       { Handle to the defProc }
  1748.             userHandle : Handle;        { General purpose handle for user}
  1749.             dataBounds : Rect;          { Total number of rows/columns}
  1750.             cells : dataHandle;         { Handle to data}
  1751.             maxIndex : Integer;         { index past the last element}
  1752.             cellArray : ARRAY[1..1] OF Integer;     { offsets to elements }
  1753.         END;
  1754. \ InitResources
  1755. 1
  1756. FUNCTION InitResources : INTEGER;
  1757.  
  1758.     InitResources is called by the system whcn it starts up, and should
  1759. not be called by the application. It initializes the Resource Manager,
  1760. opens the system resource file, reads the resource map from the file
  1761. into memory, and returns a reference number for the file.
  1762.  
  1763. (note)
  1764.     The application doesn't need the reference number for the 
  1765.     system resource file, because every Resource Manager
  1766.     routine that has a reference number as a parameter
  1767.     interprets Ø to mean the system resource file.
  1768.  
  1769.  
  1770. \ RsrcZoneInit
  1771. 1
  1772. PROCEDURE RsrcZoneInit;
  1773.  
  1774.     RsrcZoneInit is called automatically when your application starts
  1775. up, to initialize the resource map read from the system resource file;
  1776. normally you'll have no need to call it directly. It "cleans up" after
  1777. any resource access that may have been done by a previous application.
  1778. First it closes all open resource files except the system resource
  1779. file. Then, for every system resource that was read into the
  1780. application heap (that is, whose resSysHeap attribute is Ø), it
  1781. replaces the handle to that resource in the resource map with NIL.
  1782. This lets the Resource Manager know that the resource will have to be
  1783. read in again (since the previous application heap is no longer
  1784. around).
  1785.  
  1786.  
  1787. \ CreateResFile
  1788. 1
  1789. PROCEDURE CreateResFile (fileName: Str255);
  1790.  
  1791.     CreateResFile creates a resource file containing no resource data or
  1792. copy of the file's directory entry. If there's no file at all with the
  1793. given name, it also creates an empty data fork for the file. If
  1794. there's already a resource file with the given name (that is, a
  1795. resource form that isn't empty), CreateResFile will do nothing and the 
  1796. ResError function will return an appropriate Operating System result
  1797. code.
  1798.  
  1799. (note)
  1800.     Before you can work with the resource file, you need to
  1801.     open it with OpenResFile.
  1802.  
  1803.  
  1804. \ OpenResFile
  1805. 1
  1806. FUNCTION OpenResFile (fileName: Str255) : INTEGER;
  1807.  
  1808.     OpenResFile opens the resource file having the given name and makes
  1809. it the current resource file. It reads the resource map from the file
  1810. into memory and returns a reference number for the file. It also reads
  1811. in every resource whose resPreload attribute is set. If the resource
  1812. file is already open, it doesn't make it the current resource file; it
  1813. simply returns the reference number.
  1814.  
  1815. (note)
  1816.     You don't have to call OpenResFile to open the system
  1817.     Resource file or the application's resource file, because
  1818.     they're opened when the system and the application start
  1819.     up, respectively. To get the reference number of the
  1820.     application's resource file, you can call CurResFile
  1821.     after the application starts up (before you open any
  1822.     other resource file).
  1823.  
  1824.     If the file can't be opened, OpenResÏile will return -1 and the
  1825. ResError function will return an appropriate Operating System result
  1826. code. For example, an error occurs if there's no resource file with 
  1827. the given name.
  1828.  
  1829. \ CloseResFile
  1830. 1
  1831. PROCEDURE CloseResFile (refNum: INTEGER);
  1832.  
  1833.     Given the reference number of a resource file, CloseResFile does the
  1834. following:
  1835.  
  1836.     - updates the resource file by calling the UpdateResFile procedure
  1837.  
  1838.     - for each resource in the resource file, releases the memory it
  1839.       occupies by calling the ReleaseResource procedure
  1840.  
  1841.     - releases the memory occupied by the resource map
  1842.  
  1843.     - closes the resource file
  1844.  
  1845.     If there's no resource file open with the given reference number,
  1846. CloseResFile will do nothing and the ResError function will return the
  1847. result code resFNotFound. A refNum of Ø represents the system resource
  1848. file, but if you ask to close this file, CloseResFile first closes all
  1849. other open resource files.
  1850.  
  1851.     A CloseResFile of every open resource file except the system
  1852. resource file is done automatically when the application terminates. So
  1853. you only need to call CloseResFile if you want to close the system
  1854. resource file, or if you want to close any resource file before the
  1855. application terminates.
  1856.  
  1857.  
  1858. \ ResError
  1859. 1
  1860. FUNCTION ResError : INTEGER;
  1861.  
  1862.     Called after one of the various Resource Manager routines that may
  1863. result in an error condition, ResError returns a result code
  1864. identifying the error, if any. If no error occurred, it returns the
  1865. result code
  1866.  
  1867.     CONST  noErr = Ø; {no error}
  1868.  
  1869.     If an error occurred at the Operating System level, it returns an
  1870. Operating System result code, such as the File Manager "disk I/O" error
  1871. or the Memory Manager "out of memory" error. (See the File Manager and
  1872. Memory Manager manuals for a list of the result codes.)  If an error
  1873. happened at the Resource Manager level, ResError returns one of the
  1874. following result codes:
  1875.  
  1876.     CONST   resNotFound  =  -192;   {resource not found}
  1877.         resFNotFound =  -193;   {resouce file not found}
  1878.         addResFailed =  -194;   {AddResource failed}
  1879.         rmvResFailed =  -196;   {RmveResource failed}
  1880.  
  1881.     Each routine description tells which errors may occur for that
  1882. routine. You can also check for an error after system startup, which
  1883. calls InitResources, and application startup, which opens the
  1884. application's resource file.
  1885.  
  1886.  
  1887. \ CurResFile
  1888. 1
  1889. FUNCTION CurResFile  : INTEGER;
  1890.  
  1891.     CurResFile returns the reference number of the current resource file
  1892. You can call it when the application starts up to get the reference
  1893. number of its resource file.
  1894.  
  1895. (note)
  1896.     If the system resource file is the current resource file,
  1897.     CurResFile returns the actual reference number of the
  1898.     system reference file (found in the global variable
  1899.     SysMap). You needn't worry about this number being used 
  1900.     (instead of Ø in the routines that require a reference
  1901.     number; these routines recognize both Ø and the actual
  1902.     reference number as referring to the system resource
  1903.     file.
  1904.  
  1905. \ HomeResFile
  1906. 1
  1907. FUNCTION HomeResFile  (theResource: Handle)  :  INTEGER
  1908.  
  1909.     Given a handle to a resource, HomeResFile returns the reference
  1910. number of the resource file containing that resource. If the given
  1911. handle isn't a handle to a resource, HomeResFile will return -1 and the 
  1912. ResError function will return the result code resNotFound.
  1913.  
  1914.  
  1915. \ UseResFile
  1916. 1
  1917. PROCEDURE UseResFile  (refNum:  INTEGER);
  1918.  
  1919.     Given the reference number of a resource file, UseResFile sets the
  1920. current resource file to that file. If there's no resource file open
  1921. with the given reference number, UseResFile will do nothing and the
  1922. ResError function will return the result code resFNotFound. A refNum
  1923. of Ø represents the system resource file.
  1924.  
  1925.     Open resource files are arranged as a linked list; the most recently
  1926. opened file is at the end of the list and is the first one to be
  1927. searched. UseResFile lets you start the search with a file opened
  1928. earlier; the file(s) following it on the list ate then left out of the
  1929. search process. This is best understood with an example. Assume there
  1930. are four open resource files (RØ through R3); the search order is R3,
  1931. R2, R1, RØ. If you call UseResFile(R2), the search order becomes R2,
  1932. R1, RØ; R3 is no longer searched. If you then open a fifth resource
  1933. file (R4), it's added to the end of the list and the search order
  1934. becomes R4, R3, R2, R1, RØ.
  1935.  
  1936.     This procedure is useful if you no longer want to override a system
  1937. resource with one by the same name in your application's resource file. 
  1938. You can call UseResFile(Ø) to leave the application resource file out
  1939. of the search, causing only the system resource file to be searched.
  1940.  
  1941. (warning)
  1942.     Early versions of some desk accessories may, upon
  1943.     closing, always set the current resource file to the one
  1944.     opened just prior to the accessory, ignoring any
  1945.     additional resource files that may have been opened while
  1946.     the accessory was in use. To be safe, whenever desk
  1947.     accessories may have been in use, call UseResFile to
  1948.     ensure access to resource files opened after accessories.
  1949.  
  1950.  
  1951. \ CountTypes
  1952. 1
  1953. FUNCTION CountTypes : INTEGER;
  1954.  
  1955.     CountTypes returns the number of resource types in all open resource
  1956. files.
  1957.  
  1958.  
  1959. \ GetIndType
  1960. 1
  1961. PROCEDURE GetIndType (VAR theType: ResType; index: INTEGER);
  1962.  
  1963.     Given an index ranging from 1 to CountTypes (above, GetIndType
  1964. returns a resource type in theType. Called repeatedly over the entire
  1965. range  for the index, it returns all the resource types in all open
  1966. resource files. If the given index isn't in the range from 1 to
  1967. CountTypes,  GetIndType returns four NUL characters (ASCII code Ø).
  1968.  
  1969.  
  1970. \ SetResLoad
  1971. 1
  1972. PROCEDURE SetResLoad (load: BOOLEAN);
  1973.  
  1974.     Normally, the routines that return handles to resources read the
  1975. resource data into memory if it's not already in memory.
  1976. SetResLoad(FALSE) affects all those routines so that they will not read
  1977. the resource data into memory and will return an empty handle.
  1978. Resources whose resPreload attrribute is set will still be read in,
  1979. however, when a resource file is opened. SetResLoad(TRUE) restores the
  1980. normal state.
  1981.  
  1982. (warning)
  1983.     If you call SetResLoad(FALSE), be sure to restore the
  1984.     normal state as soon as possible, because other parts of
  1985.     the Toolbox that call the Resource Manager rely on it.
  1986.  
  1987.  
  1988. \ CountResources
  1989. 1
  1990. FUNCTION CountResources (theType: ResType) : INTEGER;
  1991.  
  1992.     CountResources returns the total number of resources of the given
  1993. type in all open resource files.
  1994.  
  1995.  
  1996. \ GetIndResource
  1997. 1
  1998. FUNCTION GetIndResource (theType: ResType; index: INTEGER) : Handle;
  1999.  
  2000.     Given an index ranging from 1 to CountResources(theType),
  2001. GetIndResource returns a handle to a resource of the given type (see
  2002. CountResources, above). Called repeatedly over the entire range for
  2003. the index, it returns handles to all resources of the given type in all
  2004. open resource files. GetIndResource reads the resource data into
  2005. memory if it's not already in memory, unless you've called
  2006. SetResLoad(FALSE).
  2007.  
  2008. (warning)
  2009.     The handle returned will be an empty handle if you've
  2010.     called SetResLoad(FALSE) (and the data isn't already in 
  2011.     memory). The handle will become empty if the resource
  2012.     data for a purgeable resource is read in but later
  2013.     purged. (You can test for an empty handle with, for
  2014.     example, myHndl^= NIL.)  To read in the data and make
  2015.     the handle no longer be empty, you can call LoadResource.
  2016.  
  2017.     GetIndResource returns handles for all resources in the most
  2018. recently opened resource file first, and then for those in the resource
  2019. files opened before it, in the reverse of the order that they were
  2020. opened. If you want to find out how many resources of a given type are
  2021. in a particular resource file, you can do so as follows:  Call
  2022. GetIndResource repeatedly with the index ranging from 1 to the number
  2023. of resources of that type. Pass each handle returned by GetIndResource
  2024. to HomeResFile and count all occurrences where the reference number
  2025. returned is that of the desired file. Be sure to start the index from
  2026. 1, and to call SetResLoad(FALSE) so the resources won't be read in.
  2027.  
  2028. (note)
  2029.     The UseResFile procedure affects which file the Resource
  2030.     Manager searches first when looking for a particular
  2031.     resource but not when getting indexed resources  with
  2032.     GetIndResource.
  2033.  
  2034.     If the given index isn't in the range from 1 to
  2035. CountResources(theType), GetIndResource returns NIL and the ResError
  2036. function will return the result code resNotFound. GetIndResource also
  2037. returns NIL if the resource is to be read into memory but won't fit; in
  2038. this case, ResError will return an appropriate Operating System result
  2039. code.
  2040.  
  2041.  
  2042. \ GetResource
  2043. 1
  2044. FUNCTION Get Resource (theType: ResType; the ID: INTEGER) : Handle;
  2045.  
  2046.     GetResource returns a handle to the resource having the given type
  2047. and ID number, reading the resource data into memory if it's not already
  2048. in memory and if you haven't called SetResLoad(FALSE) (see the warning 
  2049. aboove for GetIndResource). GetResource looks in the current resource
  2050. file and all resource files opened before it, in the reverse of the
  2051. order that they were opened; the system resource file is searched last.
  2052. If it doesn't find the resource, GetResource returns NIL and the 
  2053. ResError function will return the result code resNotFound. GetResource
  2054. also returns NIL if the resource is to be read into memory but won't 
  2055. fit; in this case, ResError will return an appropriate Operating System
  2056. result code.
  2057.  
  2058.  
  2059. \ GetNamedResource
  2060. 1
  2061. FUNCTION GetNamedResource (theType: ResType; name: Str255) : Handle;
  2062.  
  2063.     GetNamedResource is the same as GetResource (above) except that you
  2064. pass a resource name instead of an ID number.
  2065.  
  2066.  
  2067. \ LoadResource
  2068. 1
  2069. PROCEDURE LoadResource (theResource: Handle);
  2070.  
  2071.     Given a handle to a resource (returned by GetIndResource,
  2072. GetResource, or GetNamedResource), LoadResource reads that resource into
  2073. memory. It does nothing if the resource is already in memory or if the
  2074. given handle isn't a handle to a resource; in the latter case, the
  2075. ResError function will return the result code resNotFound. Call this
  2076. procedure if you want to access the data for a resource through its
  2077. handle and either you've called SetResLoad(FALSE) or if the resource is
  2078. purgeable.
  2079.  
  2080.     If you've changed the resource data for a purgeable resource and the 
  2081. resource is purged before being written to the resource file, the
  2082. changes will be lost; LoadResource will reread the original resource
  2083. from the resource file. See the descriptions of ChangedResource and
  2084. SetResPurge for information about how to ensure that changes made to
  2085. purgeable resources will be written to the research file.
  2086.  
  2087.  
  2088. \ ReleaseResource
  2089. 1
  2090. PROCEDURE ReleaseResource (theResource: Handle);
  2091.  
  2092.     Given a handle to a resource, ReleaseResource releases the memory
  2093. occupied by the resource data, if any, and replaces the handle to that
  2094. resource in the resource map with NIL. (See Figure 7.)  The given
  2095. handle will no longer be recognized as a handle to a resource; if the
  2096. Resource Manager is subsequently called to get the released resource, a
  2097. new handle will be allocated. Use this procedure only after you're
  2098. completely through with a resource.
  2099.  
  2100.  
  2101. \ DetachResource
  2102. 1
  2103. PROCEDURE DetachResource (theResource: Handle);
  2104.  
  2105.     Given a handle to a resource, DetachResource replaces the handle to
  2106. that resource in the resource map with NIL. (See Figure 7 above.)  The
  2107. given handle will no longer be recognized as a handle to a resource; if
  2108. the Resource Manager is subsequently called to get the detached
  2109. resource, a new handle will be allocated.
  2110.  
  2111.     DetachResource is useful if you want the resource data to be
  2112. accessed only by yourself through the given handle and not by the
  2113. Resource Manager. DetachResource is also useful in the unusual case
  2114. that you don't want a resource to be released when a resource file is
  2115. closed. To copy a resource, you can call DetachResource followed by
  2116. AddResource (with a new resource ID).
  2117.  
  2118.     If the given handle isn't a handle to a resource, DetachResopurce
  2119. will  do nothing and the ResError function will return the result code
  2120. resNotFound.
  2121.  
  2122.  
  2123. \ UniqueID
  2124. 1
  2125. FUNCTION UniqueID (theType: ResType) : INTEGER;
  2126.  
  2127.     UniqueID returns an ID number greater than Ø that isn't currently
  2128. assigned to any resource of the given type in any open resource file.
  2129. Using this number when you add a new resource to a resource file
  2130. ensures that you won't duplicate a resource ID and override an existing 
  2131. resource.
  2132.  
  2133. (warning)
  2134.     It's possible that UniqueID will return an ID in the 
  2135.     range reserved for system resources (Ø to 127). You
  2136.     should check that the ID returned is greater than 127; if
  2137.     it isn't, call UniqueID again.
  2138.  
  2139.  
  2140. \ GetResInfo
  2141. 1
  2142. PROCEDURE GetResInfo (theResource: Handle; VAR the ID: INTEGER; VAR
  2143.         theType: ResType; VAR name: Str255);
  2144.  
  2145.     Given a handle to a resource, GetResInfo returns the ID number,
  2146. type, and name of the resource. If the given handle isn't a handle to a 
  2147. resource, GetResInfo will do nothing and the ResError function will
  2148. return the result code resNotFound.
  2149.  
  2150.  
  2151. \ GetResAttrs
  2152. 1
  2153. FUNCTION GetResAttrs (theResource: Handle) : INTEGER;
  2154.  
  2155.     Given a handle to a resource, GetResAttrs returns the resource
  2156. attributes for the resource. (Resource attributes are described above
  2157. under "Resource References".)  If the given handle isn't a handle to a
  2158. resource, GetResAttrs will do nothing and the ResError function will
  2159. return the result code resNotFound.
  2160.  
  2161.  
  2162. \ SizeResource
  2163. 1
  2164. FUNCTION SizeResource (the Resource: Handle) : LONGINT;
  2165.  
  2166.     Given a handle to a resource, Size Resource returns the size in
  2167. bytes of the resource in the resource file. If the given handle isn't a
  2168. handle  to a resource, SizeResource will return -1 and the ResError
  2169. function will return the result code resNotFound. It's a good idea to
  2170. call SizeResource and ensure that sufficient space is available before
  2171. reading a resource into memory.
  2172.  
  2173.  
  2174. \ SetResInfo
  2175. 1
  2176. PROCEDURE SetResInfo (theResource: Handle; theID: INTEGER;
  2177.                         name: Str255);
  2178.  
  2179.     Given a handle to a resource, SetResInfo changes the ID number and
  2180. name of the resource to the given ID number and name.
  2181.     _______________________________________________________________
  2182.     Assembly-language note:  If you pass NIL for the name parameter,
  2183.     the name will not be changed.
  2184.     _______________________________________________________________
  2185.  
  2186. (warning)
  2187.     It's a dangerous practice to change the ID number and
  2188.     name of a system resource, because other applications may
  2189.     already access the resource and may no longer work
  2190.     properly.
  2191.  
  2192.     The change will be written to the resource file when the file is
  2193. updated if you follow SetResInfo with a call to ChangedResource.
  2194.  
  2195. (warning)
  2196.     Even if you don't call Changed Resource for this resource,
  2197.     the change may be written to the resource file when the
  2198.     file is updated. If you've ever called ChangedResource
  2199.     for any resource in the file, or if you've added or 
  2200.     removed a resource, the Resource Manager will write out
  2201.     the entire resource map when it updates the file, so all
  2202.     changes made to resource information in the map will
  2203.     become permanent. If you want any of the changes to be
  2204.     temprary, you'll have to restore the original 
  2205.     information before the file is updated.
  2206.  
  2207. SetResInfo does nothing in the following cases:
  2208.  
  2209.     - The resProtected attribute for the resource is set.
  2210.  
  2211.     - The given handle isn't a handle to a resource. The ResError
  2212.       function will return the result code resNotFound.
  2213.  
  2214.     - The resource map becomes too large to fit in memory (which can
  2215.       happen if a name is passed) or sufficient space for the modified
  2216.       resource file can't be reserved on the disk. ResError will return 
  2217.       an appropriate Operating System result code.
  2218.  
  2219.  
  2220. \ SetResAttrs
  2221. 1
  2222. PROCEDURE SetResAttrs (theResource: Handle; attrs: INTEGER);
  2223.  
  2224.     Given a handle to a resource, SetResAttrs sets the resource
  2225. attributes for the resource to attrs. (Resource attributes are
  2226. described above under "Resource Refererence".)  The resProtected
  2227. attribute takes effect immediately; the others take effect the next time
  2228. the resource is read in.
  2229.  
  2230. (warning)
  2231.     Do not use SetResAttrs to set the resChanged attribute;
  2232.     you must call Changed Resource instead. Be sure that the
  2233.     attrs parameter passed to SetResAttrs doesn't change the 
  2234.     current setting of this attribute.
  2235.  
  2236.     The attributes set with SetResAttrs will be written to the resource
  2237. file when the file is updated if you follow SetResAttrs with a call to
  2238. ChangedResource. However, even if you don't call ChangedResource for
  2239. this resource, the change may be written to the resource file when the
  2240. file is updated. See the last warning for SetResInfo (above).
  2241.  
  2242.     If the given handle isn't a handle to a resource, SetResAttrs will
  2243. do nothing and the ResError function will return the result code
  2244. resNotFound.
  2245.  
  2246.  
  2247. \ ChangedResource
  2248. 1
  2249. PROCEDURE ChangedResource (theResource: Handle);
  2250.  
  2251.     Call ChangedResource after changing either the information about a
  2252. resource in the resource map (as described above under SetResInfo and
  2253. SetResAttrs) or the resource data for a resource, if you want the
  2254. change to be permanent. Given a handle to a resource, ChangedResource
  2255. sets the resChanged attribute for the resource. This attribute tells
  2256. the Resource Manager to do both of the following:
  2257.  
  2258.     - write the resource data for the resource to the resource file when
  2259.       the file is updated or when WriteResource is called
  2260.  
  2261.     - write the entire resource map to the resource file when the file
  2262.       is updated.
  2263.  
  2264. (warning)
  2265.     If you change information in the resource map with
  2266.     SetResÈnfo or SetResAttrs and then call ChangedResource,
  2267.     remember that not only the resource map but also the
  2268.     resource data will be written out when the resource file
  2269.     is updated.
  2270.  
  2271.     To change the resource data for a purgeable resource and make the
  2272. change permanent, you have to take special precautions to ensure that
  2273. the resource won't be purged while you're changing it. You can make
  2274. the resource temporarily unpurgeable and then write it out with
  2275. WriteResource before making it purgeable again. You have to use the
  2276. Memory Manager procedures  HNoPurge and HPurge to make the resource
  2277. unpurgeable and purgeable; SetResAttrs can't be used because it won't
  2278. take effect immediately. For example:
  2279.  
  2280.     myHndl := GetResource(type,ID;  {or LoadResource(myHndl) if  }
  2281.                     { you've gotten it previously}
  2282.     HNoPurge(myHndl);       {make it unpurgeable}
  2283.       . .  .          {make the changes here}
  2284.     ChangedResource(myHndl);    {mark it changed}
  2285.         WriteResource(myHndl);      {write it out}
  2286.     HPurge(myHndl)          {make it purgeable again}
  2287.  
  2288.     Or, instead of calling WriteResource to write the data out
  2289. immediately, you can call SetResPurge(TRUE) before making any changes to
  2290. purgeable resource data.
  2291.  
  2292. ChangedResource does nothing in the following cases:
  2293.  
  2294.     - The given handle isn't a handle to a resource. The ResError
  2295.       function will return the result code resNotFound.
  2296.  
  2297.     - Sufficient space for the modified resource file can't be reserved
  2298.       on the disk. ResError will return an appropriate Operating System
  2299.       result code.
  2300.  
  2301. (warning)
  2302.     Be aware that ChangedResource (and not WriteResource)
  2303.     checks to see if there's sufficient disk space to write
  2304.     out the modified file; it there isn't enough space, the 
  2305.     resChanged attribute won't be set. This means that when 
  2306.     Write Resource is called,it won't know that the resource
  2307.     file has been changed; it won't write out the modified
  2308.     file and no error will be returned. For this reason,
  2309.     always check to see that ChangedResource returns noErr.
  2310.  
  2311.  
  2312. \ AddResource
  2313. 1
  2314. PROCEDURE AddResource (theData: Handle; theType: ResType; theID:
  2315.         INTEGER; name: Str255);
  2316.  
  2317.     Given a handle to data in memory (not a handle to an existing
  2318. resource), AddResource adds to the current resource file a resource
  2319. reference that points to the data. It sets the resChanged attribute
  2320. for the resource, so the data will be written to the resource file when
  2321. the file is updated or when WriteResource is called. If the given
  2322. handle is empty, zero-length resource data will be written.
  2323. AddResource does nothing in the following cases:
  2324.  
  2325.     - The given handle is NIL or is already a handle to an existing
  2326.       resource. The ResError function will return the result code
  2327.       addResFailed.
  2328.  
  2329.     - The resource map becomes too large to fit in memory or sufficient
  2330.       space for the modified resource file can't be reserved on the 
  2331.       disk. ResError will return an appropriate Operating System result
  2332.       code.
  2333.  
  2334. (warning)
  2335.     AddResource doesn't verify whether the resource ID you've
  2336.     passed is already assigned to another resource of the
  2337.     same type; be sure to call UniqueID before adding a
  2338.     resource.
  2339.  
  2340.  
  2341. \ RmveResource
  2342. 1
  2343. PROCEDURE RmveResource (theResource: Handle);
  2344.  
  2345.     Given a handle to a resource in the current resource file,
  2346. RmveResource removes the resource reference to the resource. The
  2347. resource data will  be removed from the resource file when the file is
  2348. updated.
  2349.  
  2350. (note)
  2351.     RmveResource doesn't release the memory occupied by the 
  2352.     resource data; to do that, call the Memory Manager
  2353.     procedure DisposHandle after calling RmveResource.
  2354.  
  2355.     If the resProtected attribute for the resource is set or if the
  2356. given handle isn't a handle to a resource in the current resource file, 
  2357. Rmve Resource will do nothing and the ResError function will return the
  2358. result code rmvResFailed.
  2359.  
  2360.  
  2361. \ UpdateResFile
  2362. 1
  2363. PROCEDURE UpdateResFile (refNum: INTEGER);
  2364.  
  2365.     Given the reference number of a resource file, UpdateResFile does
  2366. the following:
  2367.  
  2368.     - Changes, adds, or removes resource data in the file as appropriate
  2369.       to match the map. Remember that changed resource data is written
  2370.       out only if you called ChangedResource (and the call was
  2371.       successful); if you did, the resource data will be written out
  2372.       with WriteResource.
  2373.  
  2374.     - Compacts the resource file, closing up any empty space created
  2375.       when a resource was removed or made larger. (If the size of a
  2376.       changed resource is greater than its original size in the resource
  2377.       file, it's written at the end of the file rather than at its
  2378.       original location; the space occupied by the original is then
  2379.       compacted.)  UpdateResFile doesn't close up any empty space
  2380.       created when a resource is made smaller.
  2381.  
  2382.     - Writes out the resource map of the resource file, if you ever
  2383.       called ChangedResource for any resource in the file or if you
  2384.       added or removed a resource. All changes to resource information
  2385.       in the map will become permanent as a result of this, so if you
  2386.       want any such changes to be temporary, you must restore the
  2387.       original information before calling UpdateResFile.
  2388.  
  2389.     If there's no open resource file with the given reference number,
  2390. UpdateResFile will do nothing and the ResError function will return the
  2391. result code resFNotFound. A refNum of Ø represent the system resource
  2392. file.
  2393.  
  2394.     The CloseResFile procedure calls UpdateResFile before it closes the
  2395. resource file, so you only need to call UpdateResFile yourself if you
  2396. want to update the file without closing it.
  2397.  
  2398.  
  2399. \ WriteResource
  2400. 1
  2401. PROCEDURE WriteResource (theResource: Handle);
  2402.  
  2403.     Given a handle to a resource, WriteResource checks the resChanged
  2404. attribute for that resource and, if it's set (which it will be if you 
  2405. called ChangedResource or AddResource successfully), writes its
  2406. resource data to the resource file and clears its resChanged attribute.
  2407.  
  2408. (warning)
  2409.     Be aware that ChangedResource (and not WriteResource)
  2410.     determines if sufficient disk space is available to write
  2411.     out the modified file; if there isn't it will clear the 
  2412.     resChanged attribute and WriteResource will be unaware of
  2413.     the modifications. For this reason, always verify that
  2414.     ChangedResource returns noErr.
  2415.  
  2416.     If the resource is purgeable and has been purged, zero-length
  2417. resource data will be written. WriteResource does nothing if the
  2418. resProtected attribute for the resource is set or if the given handle
  2419. isn't a handle to a resource; in the latter case, the ResError function
  2420. will return the result code resNotFound.
  2421.  
  2422.     Since the resource file is updated when the application terminates
  2423. or when you call UpdateResFile (or CloseResFile, which calls
  2424. UpdateResFile), you only need to call WriteResource if you want to
  2425. write out just one or a few resources immediately.
  2426.  
  2427. (warning)
  2428.     The maximum size for resources to be written to a
  2429.     resource file is 32K bytes.
  2430.  
  2431.  
  2432. \ SetResPurge
  2433. 1
  2434. PROCEDURE SetResPurge (install: BOOLEAN);
  2435.  
  2436.     SetResPurge(TRUE) sets a  "hook" in the Memory Manager such that
  2437. before purging data specified by a handle,the Memory Manager will first
  2438. pass the handle to the Resource Manager. The Resource Manager will
  2439. determine whether the handle is that of a resource in the application
  2440. heap and, if so, will call WriteResource to write the resource data for
  2441. that resource to the resource file if its resChanged attribute is set
  2442. (see ChangedResource and WriteResource above). SetResPurge(FALSE)
  2443. restores the normal state, clearing the hook so that the Memory Manager
  2444. will once again purge without checking with the Resource Manager.
  2445.  
  2446.     SetResPurge(TRUE) is useful in applications that modify purgeable
  2447. resources. You still have to make the resources temporarily
  2448. unpurgeable while making the changes, as shown in the description of
  2449. ChangedResource, but you can set the purge hook instead of writing the
  2450. data out immediately with WriteResource. Notice that you won't know 
  2451. exactly when the resources are being written out; most applications
  2452. will want more control than this. If you wish, you can set your own
  2453. such hook; for details, refer to the section "Memory Manager Data
  2454. Structures" in the Memory Manager manual.
  2455.  
  2456.  
  2457. \ GetResFileAttrs
  2458. 1
  2459. FUNCTION GetResFileAttrs (refNum: INTEGER) : INTEGER;
  2460.  
  2461.     Given the reference number of a resource file, GetResFileAttrs
  2462. returns the resource file attributes for the file. If there's no
  2463. resource file with the given reference number, GetResFileAttrs will do
  2464. nothing and the ResError function will return the result code
  2465. resFNotFound. A refNum of Ø represents the system resource file.
  2466.  
  2467.  
  2468. \ SetResFileAttrs
  2469. 1
  2470. PROCEDURE SetResFileAttrs (refNum: INTEGER; attrs: INTEGER);
  2471.  
  2472.     Given the reference number of a resource file, SetResFileAttrs sets
  2473. the  resource file attributes of the file to attrs. If there's no
  2474. resource file with the given reference number, SetResFileAttrs will do
  2475. nothing and the ResError function will return the result code
  2476. resFNotFound. A refNum of  Ø represents the system resource file, but
  2477. you shouldn't change its resource file attributes.
  2478.  
  2479.  
  2480. \ AddReference
  2481. 1
  2482. PROCEDURE AddReference (theResource: Handle; theID: INTEGER; name:
  2483.       Str255);
  2484.  
  2485.     Given a handle to a system resource, AddReference adds to the
  2486. current resource file a system reference to the resource, giving it the
  2487. ID number and name specified by the parameters. It sets the resChanged
  2488. attribute for the resource, so the reference will be written to the
  2489. resource file when the file is updated. AddReference does nothing in
  2490. the following cases:
  2491.  
  2492.     - The current resource file is the system resource file or already
  2493.       contains a system reference to the specified resource, or the
  2494.       given handle isn't a handle to a system resource. The ResError
  2495.       function will return the result code.
  2496.  
  2497.         CONST addReFailed = -195;  (AddReference failed)
  2498.  
  2499.     - The resource map becomes too large to fit in the memory or
  2500.       sufficient space for the modified resource file can't be
  2501.       reserved on the disk. ResError will return an appropriate
  2502.       Øperating System result code.
  2503.  
  2504.  
  2505. \ RmveReference
  2506. 1
  2507. PROCEDURE RmveReference (theResource: Handle);
  2508.  
  2509.     Given a handle to a system resource, RmveReference removes the
  2510. system reference to the resource from the current resource file. (The
  2511. reference will be removed from the resource file when the file is
  2512. updated.)  RmveReference will do nothing and the ResError function will
  2513. return the result code.
  2514.  
  2515.         CONST rmvRefFailed = -197;  (RmveReference failed)
  2516.  
  2517. if any of the following are true:
  2518.  
  2519.     - The resProtected attribute for the resource is set.
  2520.  
  2521.     - There's no system reference to the resource in the current 
  2522.       resource file.
  2523.  
  2524.     - The given handle isn't a handle to a system resource. 
  2525.  
  2526. \ Count1Types
  2527. 1
  2528. FUNCTION Count1Types : INTEGER;
  2529.  
  2530.     Count1Types is the same as CountTypes except that it returns the
  2531. number of resource types in the current resource file only.
  2532.  
  2533. \ Get1IndType
  2534. 1
  2535. PROCEDURE Get1IndType (VAR theType: ResType; index: INTEGER);
  2536. ___________________________________________________________________
  2537.  
  2538. Assembly-language note:  The macro you invoke to call Get1IndType
  2539. from assembly language is named _Get1IxType.
  2540. ___________________________________________________________________
  2541.     Get1IndType is the same as GetIndType except that it searches the
  2542. current resource file only. Given an index ranging from 1 to
  2543. Count1Types (above), Get1IndType returns a resource type in theType.
  2544.  
  2545.     Called repeatedly over the entire range for the index, it returns
  2546. all the resource types in the current resource file. If the given
  2547. index isn’t in the range from 1 to Count1Types, Get1IndType returns
  2548. four NUL characters (ASCII code 0).
  2549.  
  2550. \ Count1Resources
  2551. 1
  2552. FUNCTION Count1Resources (theType: ResType) : INTEGER;
  2553.  
  2554.     Count1Resources is the same as CountResources except that it returns
  2555. the total number of resources of the given type in the current resource
  2556. file only.
  2557.  
  2558. \ Get1IndResource
  2559. 1
  2560. FUNCTION Get1IndResource (theType: ResType; index: INTEGER) : Handle;
  2561. ___________________________________________________________________
  2562.  
  2563. Assembly-language note:  The macro you invoke to call
  2564. Get1IndResource from assembly language is named _Get1IxResource.
  2565. ___________________________________________________________________
  2566.     Get1IndResource is the same as GetIndResource except that it
  2567. searches the current resource file only. Given an index ranging from 1
  2568. to Count1Resources(theType), Get1IndResource returns a handle to a
  2569. resource of the given type (see Count1Resources, above). Called
  2570. repeatedly over the entire range for the index, it returns handles to
  2571. all resources of the given type in the current resource file.
  2572.  
  2573. \ Get1Resource
  2574. 1
  2575. FUNCTION Get1Resource (theType: ResType; theID: INTEGER) : Handle;
  2576.  
  2577.     Get1Resource is the same as GetResource except that it searches the
  2578. current resource file only.
  2579.  
  2580. \ Get1NamedResource
  2581. 1
  2582. FUNCTION Get1NamedResource (theType: ResType; name: Str255) : Handle;
  2583.  
  2584.     Get1NamedResource is the same as GetNamedResource except that it
  2585. searches the current resource file only.
  2586.  
  2587. \ Unique1ID
  2588. 1
  2589. FUNCTION Unique1ID (theType: ResType) : INTEGER;
  2590.  
  2591.     Unique1ID is the same as UniqueID except that the ID number it
  2592. returns is unique only with respect to resources in the current resource
  2593. file.
  2594.  
  2595. \ MaxSizeRsrc
  2596. 1
  2597. FUNCTION MaxSizeRsrc (theResource: Handle) : LONGINT;
  2598.  
  2599.     MaxSizeRsrc is similar to SizeResource except that it does not cause
  2600. the disk to be read; instead it determines the size (in bytes) of
  2601. the resource from the offsets found in the resource map.
  2602.  
  2603.     Since MaxSizeRsrc does not read from the disk, it returns only the
  2604. maximum size of the resource. In other words, you can count on the
  2605. resource not being larger than the number of bytes reported by
  2606. MaxSizeRsrc; it’s possible, however, that the resource is actually
  2607. smaller than the resource map indicates (because the file has not
  2608. yet been compacted). If called after UpdateResFile, MaxSizeRsrc will
  2609. return the correct size of the resource.
  2610.  
  2611. \ RsrcMapEntry
  2612. 1
  2613. FUNCTION RsrcMapEntry (theResource: Handle) : LONGINT;
  2614.  
  2615.     RsrcMapEntry  provides a way to access the resource references in
  2616. the resource map. Given a handle to a resource, RsrcMapEntry returns
  2617. the offset of the resource’s reference from the beginning of the
  2618. resource map. (For more information on resource references and the
  2619. structure of a resource map, see the section “Format of a Resource File”
  2620. in the Resource Manager chapter.)  If it doesn’t find the resource,
  2621. RsrcMapEntry returns NIL and the ResError function will return the
  2622. result code resNotFound. If you pass it a NIL handle, RsrcMapEntry
  2623. will return garbage but ResError will return the result code noErr.
  2624.  
  2625. Warning:  Since routines are provided for opening, accessing,
  2626.           and changing resources, there’s really no reason to access
  2627.           resources directly. To avoid damaging the resource file, you
  2628.           should be extremely careful if you use RsrcMapEntry.
  2629.  
  2630.  
  2631. \ OpenRFPerm
  2632. 1
  2633. FUNCTION OpenRFPerm (fileName: Str255; vRefNum: INTEGER; permission: Byte) : INTEGER;
  2634.  
  2635.     OpenRFPerm is similar to OpenResFile except that it allows you to
  2636. specify the read/write permission of the resource file the first time
  2637. it is opened; OpenRFPerm also lets you specify in vRefNum the directory
  2638. or volume on which the file is located (see chapter 19 of this volume
  2639. for more details on directories). Permission can have any of the values
  2640. that you would pass to the File Manager; these values are given
  2641. in “Low-Level File Manager Routines” in chapter 19 of this volume.
  2642.  
  2643.     OpenRFPerm, like OpenResFile, will not open the specified file twice
  2644. it simply returns the reference number already assigned to the file.
  2645. In other words, OpenRFPerm cannot be used to open a second access
  2646. path to a resource file nor can it be used to change the permission
  2647. of an already open file. Since OpenRFPerm gives no indication of
  2648. whether the file was already open, there’s no way to tell whether
  2649. the file’s open permission is what you specified or what was
  2650. specified by an earlier call.
  2651.  
  2652. Note:  The shared read/write permission described in chapter 19
  2653. of this volume has no effect with OpenRFPerm since the Resource
  2654. Manager is unable to deal with a portion of a resource file.
  2655.  
  2656. \ InitGraf
  2657. 2
  2658. PROCEDURE InitGraf (globalPtr: QDPtr);
  2659.  
  2660.     Call InitGraf once and only once at the beginning of your program
  2661. to initialize QuickDraw. It initializes the QuickDraw global variables
  2662. listed below.
  2663.  
  2664.     Variable    Type        Initial Setting
  2665.     -----------------------------------------------
  2666.  
  2667.     thePort     GrafPtr     NIL
  2668.     white       Pattern     all-white pattern
  2669.     black       Pattern     all-black pattern
  2670.     gray        Pattern     50% gray pattern
  2671.     ltGray      Pattern     25% gray pattern
  2672.     dkGray      Pattern     75% gray pattern
  2673.     arrow       Cursor      pointing arrow cursor
  2674.     screenBits  BitMap      Macintosh screen, (Ø,Ø,512,342)
  2675.     randSeed    LongInt     1
  2676.  
  2677.     The globalPtr parameter tells QuickDraw where to store its global
  2678. variables, beginning with thePort. From Pascal programs, this
  2679. parameter should always be set to @the Port; assembly-language
  2680. programmers may choose any location, as long as it can accommodate the
  2681. number of bytes specified by GRAFSIZE in GRAFTYPES.TEXT (see "Using 
  2682. QuickDraw from Assembly Language").
  2683.  
  2684. (hand)
  2685.     To initialize the cursor, call InitCursor (described
  2686.     under "Cursor Handling Routines" below).
  2687.  
  2688. \ OpenPort
  2689. 2
  2690. PROCEDURE OpenPort (gp: GrafPtr);
  2691.  
  2692.     OpenPort allocates space for the given grafPort's visRgn and clipRgn 
  2693. initializes the fields of the frafPort as indicated below, and makes
  2694. the grafPort the current port (see SetPort). You must call OpenPort
  2695. before using any graf∏ort; first perform a NEW to create a grafPtr and
  2696. then use  that graf∏tr in the OpenPort call.
  2697.  
  2698.     Field       Type        Initial Setting
  2699.  
  2700.     device      INTEGER     Ø (Macintosh screen)
  2701.     portBits    BitMap      screenBits (see InitGraf)
  2702.     portRect    Rect        screenBits.bounds (Ø,Ø,512,342)
  2703.     visRgn      RgnHandle   handle to the rectangular region
  2704.                             (Ø,Ø,512,342)
  2705.     clipRgn     RgnHandle   handle to the rectangular region
  2706.                             (-3ØØØØ,-3ØØØØ,3ØØØØ,3ØØØØ)
  2707.     bkPat       Pattern     white
  2708.     fillPat     Pattern     black
  2709.     pnLoc       Point       (Ø,Ø)
  2710.     pnSize      Point       (1,1)
  2711.     pnMode      INTEGER     patCopy
  2712.     pnPat       Pattern     black
  2713.     pnVis       INTEGER     Ø (visible)
  2714.     txFont      INTEGER     Ø (system font)
  2715.     txFace      Style       normal
  2716.     txMode      INTEGER     srcOr
  2717.     txSize      INTEGER     Ø (Font Manager decides)
  2718.     spExtra     INTEGER     Ø
  2719.     fgColor     LongInt     blackColor
  2720.     bkColor     LongInt     whiteColor
  2721.     colrBit     INTEGER     Ø
  2722.     patStretch  INTEGER     Ø
  2723.     picSave     QDHandle    NIL
  2724.     rgnSave     QDHandle    NIL
  2725.     polySave    QDHandle    NIL
  2726.     grafProcs   QDProcsPtr  Nil
  2727.  
  2728.  
  2729. \ InitPort
  2730. 2
  2731. PROCEDURE InitPort (gp: GrafPtr);
  2732.  
  2733.     Given a pointer to a grafPort that has been opened with OpenPort,
  2734. InitPort reinitializes the fields of the grafPort and makes it the
  2735. current port (if it's not already).
  2736.  
  2737. (hand)
  2738.     InitPort does everything OpenPort does except allocate
  2739.     space for the visRgn and clipRgn.
  2740.  
  2741.  
  2742. \ ClosePort
  2743. 2
  2744. PROCEDURE ClosePort (gp: GrafPtr)
  2745.  
  2746.     ClosePort deallocates the space occupied by the given GrafPort's
  2747. visRgn and clipRgn. When you are completely through with a grafPort,
  2748. call this procedure and then dispose of the grafPort (with a DISPOSE of
  2749. the grafPtr).
  2750.  
  2751. (eye)
  2752.     If you do not call ClosePort before disposing of the
  2753.     grafPort, the memory used by the visRgn and clipRgn will
  2754.     be unrecoverable.
  2755.  
  2756. (eye)
  2757.     After calling ClosePort, be sure not use any copies of
  2758.     the visRgn or clipRgn handles that you may have made.
  2759.  
  2760.  
  2761. \ SetPort
  2762. 2
  2763. PROCEDURE SetPort (gp: GrafPtr);
  2764.  
  2765.     SetPort sets the grafPort indicated by gp to be the current port.
  2766. The global pointer thePort always points to the current port. All
  2767. QuickDraw drawing routines affect the bitMap thePort^.portBits and use
  2768. the local coordinate system of thePort^. Note that OpenPort and
  2769. InitPort do a SetPort to the given port.
  2770.  
  2771. (eye)
  2772.     Never do a SetPort to a port that has not been opened
  2773.     with OpenPort.
  2774.  
  2775.     Each port possesses its own pen and text characteristics which
  2776. remain unchanged when the port is not selected as the current port.
  2777.  
  2778.  
  2779. \ GetPort
  2780. 2
  2781. PROCEDURE GetPort (VAR gp: GrafPtr);
  2782.  
  2783.     GetPort returns a pointer to the current grafPort. If you have a
  2784. program that draws into more than one grafPort, it's extremely useful 
  2785. to have each procedure save the current grafPort (with GetPort), set
  2786. its own grafPort, do drawing or calculations, and then restore the
  2787. previous grafPort (with SetPort). The pointer to the current grafPort
  2788. is also available through the global pointer thePort, but you may
  2789. prefer to use GetPort for better readability of your program text. For
  2790. example, a procedure could do a GetPort (savePort) before setting its
  2791. own grafPort and a SetPort (savePort) afterwards to restore the
  2792. previous port.
  2793.  
  2794.  
  2795. \ GrafDevice
  2796. 2
  2797. PROCEDURE GrafDevice (device: INTEGER);
  2798.  
  2799.     GrafDevice sets thePort^.device to the given number, which
  2800. identifies the logical output device for this grafPort. The Font
  2801. Manager uses this information. The initial device number is Ø, which
  2802. represents the Macintosh screen.
  2803.  
  2804. \ SetPortBits
  2805. 2
  2806. PROCEDURE SetPortBits (bm: BitMap);
  2807.  
  2808.     SetPortBits sets the Port^.portBits to any previously defined
  2809. bitMap. This allows you to perform all normal drawing and calculations
  2810. on a buffer other than the Macintosh screen -- for example, a 64Ø-by-7
  2811. output buffer for a C. Itoh printer, or a small off-screen image for
  2812. later "stamping" onto the screen.
  2813.  
  2814.     Remember to prepare all fields of the bitMap before you call
  2815. SetPortBits.
  2816.  
  2817.  
  2818. \ PortSize
  2819. 2
  2820. PROCEDURE PortSize (width, height:  INTEGER);
  2821.  
  2822.     PortSize changes the size of the current grafPort's portRect. THIS 
  2823. DOES NOT AFFECT THE SCREEN; it merely changes the size of the "active
  2824. area" of the grafPort. 
  2825.  
  2826. (hand)
  2827.     This procedure is normally called only by the Window
  2828.     Manager.
  2829.  
  2830.     The top left corner of the portRect remains at its same location;
  2831. the width and height of the portRect are set to the given width and
  2832. height. In other words, PortSize moves the bottom right corner of the
  2833. portRect to a position relative to the top left corner.
  2834.  
  2835.     PortSize does not change the clipRgn or the visRgn, nor does it
  2836. affect the local coordinate system of the grafPort: it changes only the
  2837. portRect's width and height. Remember that all drawing occurs only in 
  2838. the intersection of the portBits.bounds  and the portRect, clipped to
  2839. the visRgn and the clipRgn.
  2840.  
  2841.  
  2842. \ MovePortTo
  2843. 2
  2844. PROCEDURE MovePortTo (leftGlobal,topGlobal: INTEGER);
  2845.  
  2846.     MovePortTo changes the position of the current grafPort's portRect.
  2847. THIS DOES NOT AFFECT THE SCREEN; it merely changes the location at
  2848. which subsequent drawing inside the port will appear.
  2849.  
  2850. (hand)
  2851.     This procedure is normally called only by the Window
  2852.     Manager.
  2853.  
  2854.     The leftGlobal and topGlobal parameters set the distance between the
  2855. top left corner of portBits.bounds and the top left corner of the new
  2856. portRect. For example,
  2857.  
  2858.     MovePortTo(256,171);
  2859.  
  2860. will move the top left corner of the portRect to the center of the
  2861. screen (if portBits is the Macintosh screen) regardless of the local
  2862. coordinate system.
  2863.  
  2864. Like PortSize, MovePortTo does not change the clipRgn or the visRgn,
  2865. nor does it affect the local coordinate system of the grafPort.
  2866.  
  2867.  
  2868. \ SetOrigin
  2869. 2
  2870. PROCEDURE SetOrigin (h,v: INTEGER);
  2871.  
  2872.     SetOrigin changes the local coordinate system of the current
  2873. grafPort. THIS DOES NOT AFFECT THE SCREEN; it does, however, affect
  2874. where subsequent drawing and calculation will appear in the grafPort.
  2875. SetOrigin updates the coordinates of the portBits.bounds, the portRect,
  2876. and the visRgn. All subsequent drawing and calculation routines will
  2877. use the new coordinate system.
  2878.  
  2879.     The h and v parameters set the coordinates of the top left corner of
  2880. the portRect. All other coordinates are calculated from this point.
  2881. All relative distances among any elements in the port will remain the
  2882. same; only their absolute local coordinates will change.
  2883.  
  2884. (hand)
  2885.     SetOrigin does not update the coordinates of the clipRgn
  2886.     or the pen; these items stick to the coordinate system
  2887.     (unlike the port's structure, which sticks to the 
  2888.     screen).
  2889.  
  2890.     SetOrigin is useful for adjusting the coordinate system after a
  2891. scrolling operation. (See ScrollRect under "Bit Transfer Operations"
  2892. below.)
  2893.  
  2894.  
  2895. \ SetClip
  2896. 2
  2897. PROCEDURE SetClip (rgn: RgnHandle);
  2898.  
  2899.     SetClip changes the clipping region of the current grafPort to a
  2900. region equivalent to the given region. Note that this does not change
  2901. the region handle, but affects the clipping region itself. Since SetClip
  2902. makes a copy of the given region, any subsequent changes you make to
  2903. makes a copy of the given region, any subsequent changes you make to
  2904. that region will not affect the clipping region of the port.
  2905.  
  2906.     You can set the clipping region to any arbitrary region, to aid you
  2907. in drawing inside the grafPort. The initial clipRgn is an arbitrarily
  2908. large rectangle.
  2909.  
  2910.  
  2911. \ GetClip
  2912. 2
  2913. PROCEDURE GetClip (rgn: RgnHandle);
  2914.  
  2915.     GetClip changes the given region to a region equivalent to the
  2916. clipping region of the current grafPort. This is the reverse of what
  2917. SetClip does. Like SetClip, it does not change the region handle.
  2918.  
  2919.  
  2920. \ ClipRect
  2921. 2
  2922. PROCEDURE ClipRect (r: Rect);
  2923.  
  2924.     ClipRect changes the clipping region of the current grafPort to a
  2925. rectanble equivalent to given rectangle. Note that this does not
  2926. change the region handle, but affects the region itself.
  2927.  
  2928.  
  2929. \ BackPat
  2930. 2
  2931. PROCEDURE BackPat (pat: Pattern);
  2932.  
  2933.     BackPat sets the background pattern of the current grafPort to the
  2934. given pattern. The background pattern is used in ScrollRect and in all
  2935. QuickDraw routines that perform an "erase" operation.
  2936.  
  2937.  
  2938.  
  2939.  
  2940. \ InitCursor
  2941. 2
  2942. PROCEDURE InitCursor;
  2943.  
  2944.     InitCursor sets the current cursor to the predefined arrow cursor,
  2945. an arrow pointing north-northwest, and sets the CURSOR LEVEL to Ø,
  2946. making the cursor visible. The cursor level, which is initialized to Ø
  2947. when the system is booted, keeps track of the number of times the cursor
  2948. has been hidden to compensate for nested calls to HideCursor and
  2949. ShowCursor (below).
  2950.  
  2951.     Before you call InitCursor, the cursor is undefined (or, if set by a
  2952. previous process, it's whatever that process set it to).
  2953.  
  2954.  
  2955. \ SetCursor
  2956. 2
  2957. PROCEDURE SetCursor (crsr: Cursor);
  2958.  
  2959.     SetCursor sets the current cursor to the 16-by-16-bit image in crsr.
  2960. If the cursor is hidden, it remains hidden and will attain the new
  2961. appearnce when it's uncovered; if the cursor is already visible, it
  2962. changes to the new appearance immediately.
  2963.  
  2964.     The cursor image is initialized by InitCursor to a north-northwest
  2965. arrow, visible on the screen. There is no way to retrieve the current
  2966. cursor image.
  2967.  
  2968. \ HideCursor
  2969. 2
  2970. PROCEDURE HideCursor;
  2971.  
  2972.     HideCursor removes the cursor from the screen, restoring the bits
  2973. under it, and decrements the cursor level (which InitCursor initialized
  2974. to Ø). Every call to HideCursor should be balanced by a subsequent call
  2975. to ShowCursor.
  2976.  
  2977.  
  2978. \ ShowCursor
  2979. 2
  2980. PROCEDURE ShowCursor;
  2981.  
  2982.     ShowCursor increments the cursor level, which may have been
  2983. decremented by HideCursor, and displays the cursor on the screen if the
  2984. level becomes Ø. A call to ShowCursor should balance each previous call
  2985. to HideCursor. The level is not incremented beyond Ø, so extra calls to
  2986. ShowCursor don't hurt.
  2987.  
  2988.     QuickDraw low-level interrupt-driven routines link the cursor with
  2989. the mouse position, so that if the cursor level is Ø (visible), the
  2990. cursor automatically follows the mouse. You don't need to do anything
  2991. but a ShowCursor to have a cursor track the mouse. There is  no way to
  2992. "disconnect" the cursor from the mouse; you can't force the cursor to a 
  2993. certain position, nor can you easily prevent the cursor from entering a
  2994. certain area of the screen.
  2995.  
  2996.     If the cursor has been changed (with SetCursor) while hidden,
  2997. ShowCursor presents the new cursor.
  2998.  
  2999.     The cursor is initialized by InitCursor to a north-northwest arrow,
  3000. not hidden.
  3001.  
  3002.  
  3003. \ ObscureCursor
  3004. 2
  3005. PROCEDURE ObscureCursor;
  3006.  
  3007.     ObscureCursor hides the cursor until the next time the mouse is
  3008. moved. Unlike HideCursor, it has no effect on the cursor level and must
  3009. not be balanced by a call to ShowCursor.
  3010.  
  3011. \ HidePen
  3012. 2
  3013. PROCEDURE HidePen
  3014.  
  3015.     HidePen decrements the current grafPort's pnVis field, which is 
  3016. initialized to Ø by OpenPort; whenever pnVis is negative, the pen does
  3017. not draw on the screen. PnVis keeps track of the number of times the
  3018. pen has been hidden to compensate for nested calls to HidePen and
  3019. ShowPen (below). HidePen is called by OpenRgn, OpenPicture, and
  3020. OpenPoly so that you can define regions, pictures, and polygons without
  3021. drawing on the screen.
  3022.  
  3023. \ ShowPen
  3024. 2
  3025. PROCEDURE ShowPen;
  3026.  
  3027.     ShowPen increment the current grafPort's pnVis field, which may have
  3028. been decremented by HidePen; if pnVis becomes Ø, QuickDraw resumes
  3029. drawing on the screen. Extra calls to ShowPen will increment pnVis
  3030. beyond Ø, so every call to ShowPen should be balanced by a subsequent
  3031. call to HidePen. ShowPen is called by CloseRgn, ClosePicture, and
  3032. ClosePoly.
  3033. \ GetPen
  3034. 2
  3035. PROCEDURE GetPen (VAR pt: Point);
  3036.  
  3037.     GetPen returns the current pen location, in the local coordinates of
  3038. the current grafPort.
  3039. \ GetPenState
  3040. 2
  3041. PROCEDURE GetPenState (VAR pnState: PenState);
  3042.  
  3043.     GetPenState saves the pen location, size, pattern, and mode into a
  3044. storage variable, to be restored later with SetPenState (below). This
  3045. is useful when calling short subroutines that operate in the current
  3046. port but must change the graphics pen: each such procedure can save
  3047. the pen's state when it's called, do whatever it needs to do, and
  3048. restore the previous pen state immediately before returning.
  3049.  
  3050.     The PenState data type is not useful for anything except saving the
  3051. pen's state.
  3052. \ SetPenState
  3053. 2
  3054. PROCEDURE SetPenState (pnState: PenState);
  3055.  
  3056.     SetPenState sets the pen location, size, pattern, and mode in the
  3057. current grafPort to the values stored in pnState. This is usually
  3058. called at the end of a procedure that has altered the pen parameters
  3059. and wants to restore them to their state at the beginning of the
  3060. procedure. (See GetPenState, above.)
  3061. \ PenSize
  3062. 2
  3063. PROCEDURE PenSize (width, height: INTEGER);
  3064.  
  3065.     PenSize sets the dimensions of the graphics pen in the current
  3066. grafPort. All subsequent calls to Line, LineTo, and the procedures
  3067. that draw framed shapes in the current grafPort will use the new pen
  3068. dimensions.
  3069.  
  3070.     The pen dimensions can be accessed in the variable thePort^.pnSize,
  3071. which is of type Point. If either of the pen dimensions is set to a
  3072. negative value, the pen assumes the dimensions (Ø,Ø) and no drawing is
  3073. performed. For a discussion of how the pen draws, see the "General 
  3074. Discussion of Drawing" earlier in this manuel.
  3075. \ PenMode
  3076. 2
  3077. PROCEDURE PenMode (mode: INTEGER);
  3078.  
  3079.     PenMode sets the transfer mode through which the pnPat is
  3080. transferred onto the bitMap when lines or shapes are drawn. The mode
  3081. may be any one of the pattern transfer modes:
  3082.  
  3083.     patCopy     patXor      notPatCopy  notPatXor
  3084.     patOr       patBic      notPatOr    notPatBic
  3085.  
  3086.     If the mode is one of the source transfer modes (or negative), no
  3087. drawing is performed. The current pen mode can be obtained in the
  3088. variable thePort^.pnMode. The initial pen mode is patCopy, in which
  3089. the pen pattern is copied directly to the bitMap.
  3090. \ PenPat
  3091. 2
  3092. PROCEDURE PenPat (pat: Pattern);
  3093.  
  3094.     PenPat sets the pattern that is used by the pen in the current
  3095. grafPort. The standard patterns white, black, gray, ltGray and dkGray
  3096. are predefined; the initial pnPat is black. The current pen pattern
  3097. can be obtained in the variable thePort^.onPat, and this value can be
  3098. assigned (but not compared!) to any other variable of type Pattern.
  3099. \ PenNormal
  3100. 2
  3101. PROCEDURE PenNormal;
  3102.  
  3103.     PenNormal resets the initial state of the pen in the current
  3104. grafPort, as follows:
  3105.  
  3106.     Field       Setting
  3107.     -----           -------
  3108.     pnSize      (1,1)
  3109.     pnMode      patCopy
  3110.     pnPat       black
  3111.  
  3112.     The pen location is not changed.
  3113. \ MoveTo
  3114. 2
  3115. PROCEDURE MoveTo (h,v: INTEGER);
  3116.  
  3117.     MoveTo moves the pen to location  (h,v) in the local coordinates of
  3118. the current grafPort. No drawing is performed.
  3119. \ Move
  3120. 2
  3121. PROCEDURE Move (dh,dv: INTEGER);
  3122.  
  3123.     This procedure moves the pen a distance of dh horizontally and dv
  3124. vertically from its current location; it calls MoveTo(h+dh,v+dv), where
  3125. (h,v) is the current location,  The positive directions are to the
  3126. right and down. No drawing is performed.
  3127. \ LineTo
  3128. 2
  3129. PROCEDURE LineTo (h,v: INTEGER);
  3130.  
  3131.     LineTo draws a line from the current pen location to the location
  3132. specified (in local coordinates) by h and v. The new pen location is
  3133. (h,v) after the line is drawn. See the general discussion of drawing.
  3134.  
  3135.     If a region or polygon is open and being formed, its outline is
  3136. infinitely thin and is not affected by the pnSize, pnMode, or pnPat.
  3137. (See OpenRgn and OpenPoly.)
  3138. \ Line
  3139. 2
  3140. PROCEDURE Line (dh,dv: INTEGER);
  3141.  
  3142.     This procedure draws a line to the location that is a distance of dh
  3143. horizontally and dv vertically from the current pen location; it calls
  3144. LineTo(h+dh,v+dv), where (h,v) is the current location. The positive
  3145. directions are to the right and down. The pen location becomes the
  3146. coordinates of the end of the line after the line is drawn. See the
  3147. general discussion of drawing.
  3148.  
  3149.     If a region or polygon is open and being formed, its outline is
  3150. infinitely thin and is not affected by the pnSize, pnMode, or pnPat.
  3151. (See OpenRgn and OpenPoly.)
  3152. \ TextFont
  3153. 2
  3154. PROCEDURE TextFont (font:INTEGER);
  3155.  
  3156.     TextFont sets the current grafPort's font (thePort^.txFont) to the 
  3157. given font number. The initial font number is Ø, which represents the
  3158. system font.
  3159. \ TextFace
  3160. 2
  3161. PROCEDURE TextFace (face:Style);
  3162.  
  3163.     TextFace sets the current grafPort's character style
  3164. (thePort^.txFace). The Style data type allows you to specify a set of
  3165. one or more of the following predefined constants: bold, italic,
  3166. underline, outline, shadow, condense, and extend. For example:
  3167.  
  3168.     TextFace([bold])                    {bold}
  3169.     TextFace([bold,italic]);            {bold and italic}
  3170.     TextFact(thePort^.txFace+[bold]);   {whatever it was plus bold}
  3171.     TextFace(thePort^.txFace-[bold]);   {whatever it was but not bold}
  3172.     TextFace([]);                       {normal}
  3173. \ TextMode
  3174. 2
  3175. PROCEDURE TextMode (mode: INTEGER);
  3176.  
  3177.     TextMode sets the current grafPort's transfer mode for drawing text
  3178. (thePort^.txMode). The mode should be srcOr, srcXor, or srcBic. The
  3179. initial transfer mode for drawing text is srcOR.
  3180. \ TextSize
  3181. 2
  3182. PROCEDURE TextSize (size: INTEGER);
  3183.  
  3184.     TextSize sets the current grafPort's type size (thePort^.txSize) to
  3185. the given number of points. Any size may be specified, but the result
  3186. will look best if the Font Manager has the font in that size (otherwise
  3187. it will scale a size it does have). The next best result will occur if
  3188. the given state is an even multiple of a size available for the font.
  3189. If Ø is specified, the Font Manager will choose one of the available
  3190. sizes -- whichever is closest to the system font size. The initial
  3191. txSize setting is Ø.
  3192. \ SpaceExtra
  3193. 2
  3194. PROCEDURE SpaceExtra (extra: INTEGER);
  3195.  
  3196.     SpaceExtra sets the current grafPort's spExtra field, which
  3197. specifies the number of pixels by which to widen each space in a line of
  3198. text. This is useful when text is being fully justified (that is,
  3199. aligned with both a left and a right margin). Consider, for example, a
  3200. line that contains three spaces; if there would normally be six pixels
  3201. between the end of the line and the right margin, you would call
  3202. SpaceExtra(2) to print the line with full justification. The initial
  3203. spExtra setting is Ø.
  3204.  
  3205. (hand)
  3206.     Space Extra will also take a negative argument, but be
  3207.     careful not to narrow spaces so much that the text is
  3208.     unreadabe.
  3209.  
  3210.  
  3211. \ DrawChar
  3212. 2
  3213. PROCEDURE DrawChar (ch: CHAR);
  3214.  
  3215.     DrawChar places the given character to the right of the pen
  3216. location, with the left end of its base line at the pen's location, and
  3217. advances the pen accordingly. If the character is not in the font, the
  3218. font's  missing symbol is drawn.
  3219. \ DrawString
  3220. 2
  3221. PROCEDURE DrawString (s: Str255);
  3222.  
  3223.     DrawString performs consecutive calls to DrawChar for each character
  3224. in the supplied string; the string is placed beginning at the current
  3225. pen location and extending right. No formatting (carriage returns, line
  3226. feeds, etc.)  is performed by QuickDraw. The pen location ends up to
  3227. the right of the last character in the string.
  3228. \ DrawText
  3229. 2
  3230. PROCEDURE DrawText (textBuf: QDPtr; firstByte,byteCount: INTEGER);
  3231.  
  3232.     DrawText draws text from an arbitrary structure in memory specified
  3233. by textBuf, starting first Byte bytes into the structure and continuing
  3234. for byteCount bytes. The string of text is placed beginning at the
  3235. current pen location and extending right. No formatting (carriage
  3236. returns, line feeds, etc.) is performed by QuickDraw. The pen location
  3237. ends up to the right of the last character in the string.
  3238. \ CharWidth
  3239. 2
  3240. FUNCTION CharWidth (ch: CHAR) : INTEGER;
  3241.  
  3242.     CharWidth returns the value that will be added to the pen horizontal
  3243. coordinate if the specified character is drawn. CharWidth includes the
  3244. effects of the stylistic variations set with TextFace; if you change
  3245. these after determining the character width but before actually drawing
  3246. the character, the  predetermined width may not be correct. If the
  3247. character is a space, CharWidth also includes the effect of SpaceExtra.
  3248. \ StringWidth
  3249. 2
  3250. FUNCTION StringWidth (s: Str255 ) : INTEGER;
  3251.  
  3252.     StringWidth returns the width of the given text string, which it
  3253. calculates by adding the CharWidths of all the characters in the string
  3254. (see above). This value will be added to the pen horizontal coordinate
  3255. if the specified string is drawn.
  3256. \ TextWidth
  3257. 2
  3258. FUNCTION TextWidth (textBuf: QDPtr; firstByte,byteCount: INTEGER) :
  3259.     INTEGER;
  3260.  
  3261.     TextWidth returns the width of the text stored in the arbitrary
  3262. structure in memory specified by textBuf, starting firstByte bytes into
  3263. the structure and continuing for byteCount bytes. It calculates the
  3264. width by adding the CharWidths of all the characters in the text. (See
  3265. CharWidth, above.)
  3266. \ GetFontInfo
  3267. 2
  3268. PROCEDURE GetFontInfo (VAR into: FontInfo);
  3269.  
  3270.     GetFontInfo returns the following information about the current
  3271. grafPort's character font, taking into consideration the style and size 
  3272. in which the characters will be drawn:  the ascent, descent, maximum
  3273. character width (the greatest distance the pen will move when a
  3274. character is drawn), and leading (the vertical distance between the
  3275. descent line and the ascent line below it), all in pixels. The
  3276. FontInfo data structure is defined as:
  3277.  
  3278.     TYPE FontInfo = RECORD
  3279.             ascent:  INTEGER;
  3280.             descent: INTEGER;
  3281.             widMax:  INTEGER;
  3282.             leading: INTEGER;
  3283.           END;
  3284. \ Forecolor
  3285. 2
  3286. PROCEDURE ForeColor (color: LongInt);
  3287.  
  3288.     ForeColor sets the foreground color for all drawing in the current
  3289. grafPort (^thePort.fgColor) to the given color. The following standard
  3290. colors are predefined:  blackColor, whiteColor, redColor, greenColor,
  3291. blueColor, cyanColor, magentaColor, and yellowColor. The initial
  3292. foreground color is blackColor.
  3293. \ BackColor
  3294. 2
  3295. PROCEDURE BackColor (color: LongInt)
  3296.  
  3297.     BackColor sets the background color for all drawing in the current
  3298. grafPort (^thePort.bkColor) to the given color.  Eight standard colors
  3299. are predefined (see ForeColor above). The initial background color is
  3300. whiteColor.
  3301. \ ColorBit
  3302. 2
  3303. PROCEDURE ColorBit (whichBit: INTEGER);
  3304.  
  3305.     ColorBit is called by printing software for a color printer, or
  3306. other color-imaging software, to set the current grafPort's colrBit
  3307. field to whichBit; this tells QuickDraw which plane of the color picture
  3308. to draw into. QuickDraw will draw into the plane corresponding to bit
  3309. number whichBit. Since QuickDraw can support output devices that have
  3310. up to 32 bits of color information per pixel, the possible range of
  3311. values for whichBit is Ø through 31. The initial value of the colrBit
  3312. field is Ø.
  3313. \ SetRect
  3314. 2
  3315. PROCEDURE SetRect (VAR r: Rect; left,top,right, bottom; INTEGER);
  3316.  
  3317.     SetRect assigns the four boundary coordinates to the rectangle. The
  3318. result is a rectangle with coordinates (left,top,right,bottom).
  3319.  
  3320.     This procedure is supplied as a utility to help you shorten your
  3321. program text. If you want a more readable text at the expense of
  3322. length, you can assign integers (or points) directly into the
  3323. rectangle's fields. There is no significant code size or execution 
  3324. speed advantage to either method; one's just easier to write, and the 
  3325. other's easier to read.
  3326. \ OffSetRect
  3327. 2
  3328. PROCEDURE OffsetRect (VAR r: Rect; dh,dv: INTEGER);
  3329.  
  3330.     OffsetRect moves the rectangle by adding dh to each horizontal
  3331. coordinate and dv to each vertical coordinate. If dh and dv are
  3332. positive, the movement is to the right and down; if either is negative,
  3333. the corresponding movement is in the opposite direction. The rectangle
  3334. retains its shape and size; it's merely moved on the coordinate plane. 
  3335. This does not affect the screen unless you subsequently call a routine
  3336. to draw within the rectangle.
  3337. \ InsetRect
  3338. 2
  3339. PROCEDURE InsetRect (VAR r: Rect; dh,dv: INTEGER);
  3340.  
  3341.     InsetRect shrinks or expands the rectangle. The left and right
  3342. sides are moved in by the amount specified by dh; the top and bottom are
  3343. moved towards the center by the amount specified by dv. If dh or dv is
  3344. negative, the appropriate pair of sides is moved outwards instead of
  3345. inwards.  The effect is to alter the size by 2*dh horizontally and 2*dv
  3346. vertically, with the rectangle remaining centered in the same place on
  3347. the coordinate plane.
  3348.  
  3349.     If the resulting width or height becomes less than 1, the rectangle
  3350. is set to the empty rectangle (Ø,Ø,Ø,Ø).
  3351. \ SectRect
  3352. 2
  3353. FUNCTION SectRect(srcRectA,srcRectB: Rect; VAR dstRect: Rect) :
  3354.     BOOLEAN;
  3355.  
  3356.     SectRect calculates the rectangle that is the intersection of the
  3357. two input rectangles, and returns TRUE if they indeed intersect or FALSE
  3358. if they do not. Rectangles that "touch" at a line or a point are not
  3359. considered intersecting, because their intersection rectangle (really,
  3360. in this case, an intersection line or point) does not enclose any bits
  3361. on the bitMap.
  3362.  
  3363.     If the rectangles do not intersect, the destination rectangle is set
  3364. to (Ø,Ø,Ø,Ø,). SectRect works correctly even if one of the source
  3365. rectangles is also the destination.
  3366. \ UnionRect
  3367. 2
  3368. PROCEDURE UnionRect (srcRectA,srcRectB: Rect; VAR dstRect: Rect);
  3369.  
  3370.     Union Rect calculates the smallest rectangle which encloses both
  3371. input rectangles. It works correctly even if one of the source
  3372. rectangles is also the destination.
  3373. \ PtInRect
  3374. 2
  3375. FUNCTION PtInRect (pt: Point; r: Rect) : BOOLEAN;
  3376.  
  3377.     PtInRect determines whether the pixel below and to the right of the
  3378. given coordinate point is enclosed in the specified rectangle, and
  3379. returns TRUE if so or FALSE if not.
  3380. \ Pt2Rect
  3381. 2
  3382. PROCEDURE Pt2Rect (ptA,ptB: Point; VAR: dstRect: Rect);
  3383.  
  3384.     Pt2Rect returns the smallest rectangle which encloses the two input
  3385. points.
  3386. \ PtToAngle
  3387. 2
  3388. PROCEDURE PtToAngle (r: Rect; pt: Point; VAR angle: INTEGER);
  3389.  
  3390.     PtToAngle calculates an integer angle between a line from the center
  3391. of the rectangle to the given point and a line from the center of the
  3392. rectangle pointing straight up (12 o'clock high). The angle is in 
  3393. degrees from Ø to 359, measured clockwise from 12 o'clock, with 9Ø
  3394. degrees at 3 o'clock, 18Ø at 6o'clock, and 27Ø at 9 o'clock. Other
  3395. angles are measured relative to the rectangle: if the line to the
  3396. given point goes through the top right corner of the rectangle, the
  3397. angle returned is 45 degrees, even if the rectangle is not square; if
  3398. it goes through the bottom right corner, the angle is 135 degrees, and
  3399. so on (see Figure 18).
  3400.  
  3401.     The angle returned might be used as input to one of the procedures
  3402. that manipulate arcs and wedges, as described below under "Graphic 
  3403. Operations on Arcs and Wedges".
  3404. \ EqualRect
  3405. 2
  3406. FUNCTION EqualRect (rectA,rectB: Rect) : BOOLEAN;
  3407.  
  3408.     EqualRect compares the two rectangles and returns TRUE if they are
  3409. equal or FALSE if not. The two rectangles must have identical boundary
  3410. coordinates to be considered equal.
  3411.  
  3412.  
  3413. \ EmptyRect
  3414. 2
  3415. FUNCTION EmptyRect (r: Rect) : BOOLEAN;
  3416.  
  3417.     EmptyRect returns TRUE if the given rectangle is an empty rectangle
  3418. or FALSE if not. A rectangle is considered empty if the bottom
  3419. coordinate is equal to or less than the top or the right coordinate is
  3420. equal to or less than the left.
  3421. \ FrameRect
  3422. 2
  3423. PROCEDURE FrameRect (r: Rect);
  3424.  
  3425.     FrameRect draws a hollow outline just inside the specified rectangle
  3426. using the current grafPort's pen pattern, mode, and size. The outline 
  3427. is as wide as the pen width and as tall as the pen height. It is drawn
  3428. with the pnPat, according to the pattern transfer mode specified by
  3429. pnMode. The pen location is not changed by this procedure.
  3430.  
  3431.     If a region is open and being formed, the outside outline of the new
  3432. rectangle is mathematically added to the region's boundary.
  3433. \ PaintRect
  3434. 2
  3435. PROCEDURE PaintRect (r: Rect);
  3436.  
  3437.     PaintRect paints the specified rectangle with the current grafPort's 
  3438. pen pattern and mode. The rectangle on the bitMap is filled with the
  3439. pnPat, according to the pattern transfer mode specified by pnMode. The
  3440. pen location is not changed by this procedure.
  3441. \ EraseRect
  3442. 2
  3443. PROCEDURE EraseRect (r: Rect);
  3444.  
  3445.     EraseRect paints the specified rectangle with the current grafPort's 
  3446. background pattern bkPat (in patCopy mode). The grafPort's pnPat and 
  3447. pnMode are ignored; the pen location is not changed.
  3448. \ InvertRect
  3449. 2
  3450. PROCEDURE InvertRect (r: Rect);
  3451.  
  3452.                 __________________________________________________________________
  3453.                      Assembly-Language note: The macro you invoke to call InvertRect
  3454.                         from  assembly language is named _InverRect.
  3455.                 __________________________________________________________________
  3456.  
  3457.     InvertRect inverts the pixels enclosed by the specified rectangle:
  3458. every white pixel becomes black and every black pixel becomes white.
  3459. The grafPort's pnPat, pnMode, and bkPat are all ignored; the pen 
  3460. location is not changed.
  3461. \ FillRect
  3462. 2
  3463. PROCEDURE FillRect (r: Rect; pat: Pattern);
  3464.  
  3465.     FillRect fills the specified rectangle with the given pattern (in
  3466. patCopy mode). The grafPort's pnPat, pnMode, and bkPat are all 
  3467. ignored; the pen location is not changed.
  3468. \ FrameOval
  3469. 2
  3470. PROCEDURE FrameOval (r: Rect);
  3471.  
  3472.     FrameOval draws a hollow outline just inside the oval that fits
  3473. inside the specified rectangle, using the current grafPort's pen
  3474. pattern, mode, and size. The outline is as wide as the pen width and as
  3475. tall as the pen height. It is drawn with the pnPat, according to the
  3476. pattern transfer mode specified by pnMode. The pen location is not
  3477. changed by this procedure.
  3478.  
  3479.     If a region is open and being formed, the outside outline of the new
  3480. oval is mathematically added to the region's boundary.
  3481. \ PaintOval
  3482. 2
  3483. PROCEDURE PaintOval (r: Rect);
  3484.  
  3485.     PaintOval paints an oval just inside the specified rectangle with
  3486. the current grafPort's pen pattern and mode. The oval on the bitMap is 
  3487. filled with the pnPat, according to the pattern transfer mode specified
  3488. by pnMode. The pen location is not changed by this procedure.
  3489. \ EraseOval
  3490. 2
  3491. PROCEDURE EraseOval (r: Rect);
  3492.  
  3493.     EraseOval paints an oval just inside the specified rectangle with
  3494. the current grafPort's background pattern bkPat (in patCopy mode). The 
  3495. grafPort's pnPat and pnMode are ignored; the pen location is not  
  3496. changed.
  3497. \ InvertOval
  3498. 2
  3499. PROCEDURE InvertOval (r: Rect);
  3500.  
  3501.     InvertOval inverts the pixels enclosed by an oval just inside the
  3502. specified rectangle: every white pixel becomes black and every black
  3503. pixel becomes white. The grafPort's pnPat, pnMode, and bkPat are all 
  3504. ignored; the pen location is not changed.
  3505. \ FillOval
  3506. 2
  3507. PROCEDURE FillOval (r: Rect; pat: Pattern);
  3508.  
  3509.     FillOval fills an oval just inside the specified rectangle with the
  3510. given pattern in patCopy mode). The grafPort's pnPat, pnMode, and 
  3511. bkPat are all ignored; the pen location is not changed.
  3512. \ FrameRoundRect
  3513. 2
  3514. PROCEDURE FrameRoundRect (r: Rect; ovalWidth,ovalHeight: INTEGER);
  3515.  
  3516.     FrameRoundRect draws a hollow outline just inside the specified
  3517. rounded-corner rectangle, using the current grafPort's pen pattern, 
  3518. mode, and size. OvalWidth and ovalHeight specify the diameters of
  3519. curvature for the corners (see Figure 19). The outline is as wide as
  3520. the pen width and as tall as the pen height. It is drawn with the
  3521. pnPat, according to the pattern transfer mode specified by pnMode. The
  3522. pen location is not changed by this procedure.
  3523.  
  3524.     If a region is open and being formed, the outside outline of the new
  3525. rounded-corner rectangle is mathematically added to the region's 
  3526. boundary.
  3527. \ PaintRoundRect
  3528. 2
  3529. PROCEDURE PaintRoundRect (r: Rect; ovalWidth,ovalHeight: INTEGER);
  3530.  
  3531.     PaintRoundREct paints the specified rounded-corner rectangle with
  3532. the current grafPort's pen pattern and mode. OvalWidth and ovalHeight
  3533. specify the diameters of curvature for the corners. The rounded-corner
  3534. rectangle on the bitMap is filled with the pnPat, according to the
  3535. pattern transfer mode specified by pnMode. The pen location is not
  3536. changed by this procedure.
  3537. \ EraseRoundRect
  3538. 2
  3539. PROCEDURE EraseRoundRect (r: Rect; ovalWidth,ovalHeight: INTEGER);
  3540.  
  3541.     EraseRoundRect paints the specified rounded-corner rectangle with
  3542. the current grafPort's background pattern bkPat (in patCopy mode).
  3543.  
  3544.     OvalWidth and ovalHeight specify the diameters of curvature for the
  3545. corners. The grafPort's pnPat and pnMode are ignored; the pen location 
  3546. is not changed.
  3547. \ InvertRoundRect
  3548. 2
  3549. PROCEDURE InvertRoundRect (r: Rect; ovalWidth,ovalHeight: INTEGER);
  3550.  
  3551.     InvertRoundRect inverts the pixels enclosed by the specified
  3552. rounded-corner rectangle: every white pixel becomes black and every
  3553. black pixel becomes white. OvalWidth and ovalHeight specify the
  3554. diameters of curvature for the corners. The grafPort's pnPat, pnMode,
  3555. and bkPat are all ignored; the pen location is not changed.
  3556. \ FillRoundRect
  3557. 2
  3558. PROCEDURE FillRoundRect (r: Rect; ovalWidth,ovalHeight: INTEGER; pat:
  3559.                             Pattern);
  3560.  
  3561.     FillRoundRect fills the specified rounded-corner rectangle with the
  3562. given pattern (in patCopy mode). OvalWidth and ovalHeight specify the
  3563. diameters of curvature for the corners. The grafPort's pnPat, pnMode, 
  3564. and bkPat are all ignored; the pen location is not changed.
  3565. \ FrameArc
  3566. 2
  3567. PROCEDURE FrameArc (r: Rect; startAngle,arcAngle: INTEGER);
  3568.  
  3569.     FrameArc draws an arc of the oval that fits inside the specified
  3570. rectangle, using the current grafPort's pen pattern, mode, and size.
  3571. StartAngle indicates where the arc begins and is treated mod 36Ø.
  3572. ArcAngle defines the extent of the arc. The angles are given in
  3573. positive or negative degrees; a positive angle goes clockwise, while a
  3574. negative angle goes counterclockwis. Zero degrees is at l2 o'clock,
  3575. high, 9Ø (or -27Ø) is at 3 o'clock, 18Ø (or -18Ø) is at 6 o'clock, and
  3576. 27Ø (or -9Ø) is at 9 o'clock. Other angles are measured relative to
  3577. the enclosing rectangle:  a line from the center of the rectangle
  3578. through its top right corner is at 45 degrees, even if the rectangle is
  3579. not square; a line through the bottom right corner is at 135 degrees,
  3580. and so on (see Figure 2Ø).
  3581.  
  3582.     The arc is as wide as the pen width and as tall as the pen height.
  3583. It is drawn with the pnPat, according to the pattern transfer mode
  3584. specified by pnMode. The pen location is not changed by this
  3585. procedure.
  3586.  
  3587. (eye)
  3588.     FrameArc differs from other QuickDraw procedures that
  3589.     frame shapes in that the arc is not mathematically added
  3590.     to the boundary of a region that is open and being
  3591.     formed.
  3592.  
  3593.  
  3594. \ PaintArc
  3595. 2
  3596. PROCEDURE PaintArc (r: Rec; startAngle,arcAngle: INTEGER);
  3597.  
  3598.     PaintArc paints a wedge of the oval just inside the specified
  3599. rectangle with the current grafPort's pen pattern and mode. StartAngle
  3600. and arcAngle define the arc of the wedge as in FrameArc. The wedge on
  3601. the bitMap is filled with the pnPat, according to the pattern transfer
  3602. mode specified by pnMode. The pen location is not changed by this
  3603. procedure.
  3604.  
  3605.  
  3606. \ EraseArc
  3607. 2
  3608. PROCEDURE EraseArc (r: Rect; startAngle,arcAngle: INTEGER);
  3609.  
  3610.     EraseArc paints a wedge of the oval just inside the specified
  3611. rectangle with the current grafPort's background pattern bkPat (in
  3612. patCopy mode). StartAngle and arcAngle define the arc of the wedge as in
  3613. FrameArc. The grafPort's pnPat and pnMode are ignored; the pen location
  3614. is not changed.
  3615. \ InvertArc
  3616. 2
  3617. PROCEDURE InvertArc (r: Rect; startAngle,arcAngle: INTEGER);
  3618.  
  3619.     InvertArc inverts the pixels enclosed by a wedge of the oval just
  3620. inside the specified rectangle:  every white pixel becomes black and
  3621. every black pixel becomes white. StartAngle and arcAngle define the
  3622. arc of the wedge as in FrameArc. The grafPort's pnPat, pnMode, and 
  3623. bkPat are all ignored; the pen location is not changed.
  3624. \ FillArc
  3625. 2
  3626. PROCEDURE FillArc (r: Rect; startAngle,arcAngle: INTEGER; pat:
  3627.     Pattern);
  3628.  
  3629.     FillArc fills a wedge of the oval just inside the specified
  3630. rectangle with the given pattern (in patCopy mode). StartAngle and
  3631. arcAngle define the arc of the wedge as in FrameArc. The grafPort's
  3632. pnPat, pnMode, and bkPat are all ignored; the pen lcoation is not
  3633. changed.
  3634. \ NewRgn
  3635. 2
  3636. FUNCTION NewRgn : RgnHandle;
  3637.  
  3638.     NewRgn allocates space for a new, dynamic, variable-size region,
  3639. initializes it to the empty region (Ø,Ø,Ø,Ø), and returns a handle to
  3640. the new region. Only this function creates new regions; all other
  3641. procedures just alter the size and shape of regions you create.
  3642. OpenPort calls NewRgn to allocate space for the port's visRgn and 
  3643. clipRgn.
  3644.  
  3645. (eye)
  3646.     Except when using visRgn or clipRgn, you MUST call NewRgn
  3647.     before specifying a region's handle in any drawing or 
  3648.     calculation procedure.
  3649.  
  3650. (eye)
  3651.     Never refer to a region without using its handle.
  3652. \ DisposeRgn
  3653. 2
  3654. PROCEDURE DisposeRgn (rgn: RgnHandle);
  3655.  
  3656.     DisposeRgn deallocates space for the region whose handle is supplied
  3657. and returns the memory used by the region to the free memory pool. Use
  3658. this only after you are completely through with a temporary region.
  3659.  
  3660. (eye)
  3661.     Never use a region once you have deallocated it, or you
  3662.     will risk being hung by dangling pointers!
  3663. \ CopyRgn
  3664. 2
  3665. PROCEDURE CopyRgn (srcRgn,dstRgn: RgnHandle);
  3666.  
  3667.     CopyRgn copies the mathematical structure of arcRgn into dstRgn;
  3668. that is, it makes a duplicate copy of srcRgn. Once this is done, srcRgn
  3669. may be altered (or even disposd of) without affecting dstRgn. COPYRGN
  3670. DOES NOT CREATE THE DESTINATION REGION:  you must use NewRgn to create
  3671. the dstRgn before you call CopyRgn.
  3672. \ SetEmptyRgn
  3673. 2
  3674. PROCEDURE SetEmptyRgn (rgn: RgnHandle);
  3675.  
  3676.     Set EmptyRgn destroys the previous structure of the given region,
  3677. then sets the new structure to the empty region (Ø,Ø,Ø,Ø).
  3678. \ SetRectRgn
  3679. 2
  3680. PROCEDURE SetRectRgn (rgn: RgnHandle; left,top,right,bottom: INTEGER);
  3681.  
  3682.     SetRectRgn destroys the previous structure of the given region, then
  3683. sets the new structure to the rectangle specified by left, top, right,
  3684. and bottom.
  3685.  
  3686.     If the specified rectangle is empty (i.e., left>=right or
  3687. top>=Bottom), the region is set to the empty region (Ø,Ø,Ø,Ø).
  3688. \ RectRgn
  3689. 2
  3690. PROCEDURE RectRgn (rgn: RgnHandle; r: Rect);
  3691.  
  3692.     RectRgn destroys the previous structure of the given region, then
  3693. sets the new structure to the rectangle specified by r. This is
  3694. operationally synonymous with SetRectRgn, except the input rectangle is
  3695. defined by a rectangle rather than by four boundary coordinates.
  3696. \ OpenRgn
  3697. 2
  3698. PROCEDURE OpenRgn;
  3699.  
  3700.     OpenRgn tells QuickDraw to allocate temporary space and start saving
  3701. lines and framed shapes for later processing as a region definition.
  3702. While a region is open, all calls to Line, LineTo, and the procedures
  3703. that draw framed shapes (except arcs) affect the outline of the region.
  3704. Only the line endpoints and shape boundaries affect the region
  3705. definition; the pen mode, pattern, and size do not affect it. In fact,
  3706. OpenRgn calls HidePen, so no drawing occurs on the screen while the
  3707. region is open (unless you called ShowPen just after Open Rgn, or you
  3708. called ShowPen previously without balancing it by a call to HidePen).
  3709. Since the pen hangs below and to the right of the pen location, drawing
  3710. lines with even the smallest pen will change bits that lie outside the
  3711. region you define.
  3712.  
  3713.     The outline of a region is mathematically defined and infinitely
  3714. thin, and separates the bitMap into two groups of bits:  those within
  3715. the region and those outside it. A region should consist of one or more
  3716. closed loops. Each framed shape itself constitutes a loop. Any lines
  3717. drawn with Line or LineTo should connect with each other or with a
  3718. framed shape. Even though  the on-screen presentation of a region is
  3719. clipped, the definition of a region is not; you can define a region
  3720. anywhere on the coordinate plane with complete disregard for the
  3721. location of various grafPort entities on that plane.
  3722.  
  3723.     When a region is open, the current grafPort's rgnSave field contains
  3724. a handle to information related to the region definition. If you want
  3725. to temporarily disable the collection of lines and shapes, you can save
  3726. the current value of this field, set the field to NIL, and later
  3727. restore the saved value to resume the region definition.
  3728.  
  3729. (eye)
  3730.     Do not call OpenRgn while another region is already open.
  3731.     All open regions but the most recent will behave
  3732.     strangely.
  3733. \ CloseRgn
  3734. 2
  3735. PROCEDURE CloseRgn (dstRgn: RgnHandle);
  3736.  
  3737.     CloseRgn stops the collection of lines and framed shapes, organizes
  3738. them into a region definition, and saves the resulting region into the
  3739. region indicated by dstRgn. You should perform one and only one
  3740. CloseRgn for every OpnRgn. CloseRgn calls ShowPen, balancing the
  3741. HidePen call made by OpenRgn.
  3742.  
  3743.     Here's an example of how to create and open a region, define a
  3744. barbell shape, close the region, and draw it:
  3745.  
  3746.     barbell := NewRgn;                  {make a new region}
  3747.     OpenRgn;                            {begin collecting stuff}
  3748.        SetRect(tempRect,2Ø,2Ø,3Ø,5Ø);   {form the left weight}
  3749.        FrameOval(tempRect);
  3750.        SetRect(tempRect,3Ø,3Ø,8Ø,4Ø);   {form the bar}
  3751.        FrameRect(tempRect);
  3752.        SetRect(tempRect(8Ø,2Ø,9Ø,5Ø);   {form the right weight}
  3753.        FrameOval(tempRect);
  3754.     CloseRgn(barbell);                  {we're done; save in barbell}
  3755.     FillRgn(barbell,black);             {draw it on the screen}
  3756.     DisposeRgn(barbell);                {we don't need you anymore...}
  3757. \ OffsetRgn
  3758. 2
  3759. PROCEDURE OffsetRgn (rgn: RgnHandle; dh,dv: INTEGER);
  3760.  
  3761.     OffsetRgn moves the region on the coordinate plane, a distance of dh
  3762. horizontally and dv vertically. This does not affect the screen unless
  3763. you subsequently call a routine to draw the region. If dh and dv are
  3764. positive, the movement is to the right and down; if either is negative,
  3765. the corresponding movement is in the opposite direction. The region
  3766. retains its size and shape.
  3767.  
  3768. (hand)
  3769.     OffsetRgn is an especially efficient operation, because
  3770.     most of the data defining a region is stored relative to
  3771.     rgnBBox and so isn't actually changed by OffsetRgn.
  3772. \ InsetRgn
  3773. 2
  3774. PROCEDURE InsetRgn (rgn: RgnHandle; dh,dv: INTEGER);
  3775.  
  3776.     InsetRgn shrinks or expands the region. All points on the region
  3777. boundary are moved inwards a distance of dv vertically and dh
  3778. horizontally; if dh or dv is negative, the points are moved outwards in
  3779. that direction. InsetRgn leaves the region "centered" at the same
  3780. position, but moves the outline in (for positive values of dh and dv)
  3781. or out (for negative values of dh and dv). InsetRgn of a rectangular
  3782. region works just like InsetRect.
  3783. \ SectRgn
  3784. 2
  3785. PROCEDURE SectRgn (srcRgnA,srcRgnB,dstRgn: RgnHandle);
  3786.  
  3787.     SectRgn calculates the intersection of two regions and places the
  3788. intersection in a third region. THIS DOES NOT CREATE THE DESTINATION
  3789. REGION:  you must use NewRgn to create the dstRgn before you call
  3790. SectRgn. The dstRgn can be one of the source regions, if desired.
  3791.  
  3792.     If the regions do not intersect, or one of the regions is empty, the
  3793. destination is set to the empty region (Ø,Ø,Ø,Ø).
  3794. \ UnionRgn
  3795. 2
  3796. PROCEDURE UnionRgn (srcRgnA,srcRgnB,dstRgn: RgnHandle);
  3797.  
  3798.     UnionRgn calculates the union of two regions and places the union in
  3799. a third region. THIS DOES NOT CREATE THE DESTINATION REGION:  you must
  3800. use NewRgn to create the dstRgn before you call UnionRgn. The dstRgn
  3801. can be one of the source regions, if desired.
  3802.  
  3803.     If both regions are empty, the destination is set to the empty
  3804. region (Ø,Ø,Ø,Ø).
  3805. \ DiffRgn
  3806. 2
  3807. PROCEDURE DiffRgn (srcRgnA,srcRgnB,dstRgn: RgnHandle);
  3808.  
  3809.     DiffRgn subtracts  srcRgnB from srcRgnA and places the difference in
  3810. a third region. THIS DOES NOT CREATE THE DESTINATION REGION:  You must
  3811. use NewRgn to create the dstRgn before you call DiffRgn. The dstRgn
  3812. can be one of the source regions, if desired.
  3813.  
  3814.     If the first source region is empty, the destination is set to the
  3815. empty region (Ø,Ø,Ø,Ø).
  3816. \ XorRgn
  3817. 2
  3818. PROCEDURE XorRgn (srcRgnA,srcRgnB,dstRgn: RgnHandle);
  3819.  
  3820.     XorRgn calculates the difference between the union and the
  3821. intersection of two regions and places the result in a third region.
  3822. THIS DOES NOT CREATE THE DESTINATION REGION:  you must use NewRgn to
  3823. create the dstRgn before you call XorRgn. The dstRgn can be one of the
  3824. source regions, if desired.
  3825.  
  3826.     If the regions are coincident, the destination is set to the empty
  3827. region (Ø,Ø,Ø,Ø).
  3828. \ PtInRgn
  3829. 2
  3830. FUNCTION PtInRgn (pt: Point; rgn: RgnHandle) : BOOLEAN;
  3831.  
  3832.     PtInRgn checks whether the pixel below and to the right of the given
  3833. coordinate point is within the specified region, and returns TRUE if so
  3834. or FALSE if not.
  3835. \ RectInRgn
  3836. 2
  3837. FUNCTION RectInRgn (r: Rect; rgn: RgnHandle) : BOOLEAN;
  3838.  
  3839.     RectInRgn checks whether the given rectangle intersects the
  3840. specified region, and returns TRUE if the intersection encloses at least one bit
  3841. or FALSE if not.
  3842. \ EqualRgn
  3843. 2
  3844. FUNCTION EqualRgn (rgnA,rgnB: RgnHandle) : BOOLEAN;
  3845.  
  3846. EqualRgn compares the two regions and returns TRUE if they are equal
  3847. or FALSE if not. The two regions must have identical sizes, shapes, and
  3848. locations to be considered equal. Any two empty regions are always
  3849. equal.
  3850. \ EmptyRgn
  3851. 2
  3852. FUNCTION EmptyRgn (rgn: RgnHandle) : BOOLEAN;
  3853.  
  3854.     EmptyRgn returns TRUE if the region is an empty region or FALSE if
  3855. not. Some of the circumstances in which an empty region can be created
  3856. are: a NewRgn call; a CopyRgn of an empty region; a SetRectRgn or
  3857. RectRegn with an empty rectangle as an argument; CloseRgn without a
  3858. previous OpenRgn or with no drawing after an OpenRgn; OffsetRgn of an
  3859. empty region; InsetRgn with an empty region or too large an inset;
  3860. SectRgn of nonintersecting regions; UnionRgn of two empty regions; and
  3861. DiffRgn or XorRgn of two identical or nonintersecting regions.
  3862. \ FrameRgn
  3863. 2
  3864. PROCEDURE FrameRgn (rgn: RgnHandle);
  3865.  
  3866.     FrameRgn draws a hollow outline just inside the specified region,
  3867. using the current grafPort's pen pattern, mode, and size. The outline
  3868. is as wide as the pen width and as tall as the pen height; under no
  3869. circumstances will the frame go outside the region boundary. The pen
  3870. location is not changed by this procedure.
  3871.  
  3872.     If a region is open and being formed, the outside outline of the
  3873. region being framed is mathematically added to that region's boundary.
  3874. \ PaintRgn
  3875. 2
  3876. PROCEDURE PaintRgn (rgn: RgnHandle);
  3877.  
  3878.     PaintRgn paints the specified region with the current grafPort's pen 
  3879. pattern and pen mode. The region on the bitMap is filled with the
  3880. pnPat, according to the pattern transfer mode specified by pnMode. The
  3881. pen location is not changed by this procedure.
  3882. \ EraseRgn
  3883. 2
  3884. PROCEDURE EraseRgn (rgn: RgnHandle);
  3885.  
  3886.     EraseRgn paints the specified region with the current grafPort's
  3887. background pattern bkPat (in patCopy mode). The grafPort's pnPat and 
  3888. pnMode are ignored; the pen location is not changed.
  3889. \ InvertRgn
  3890. 2
  3891. PROCEDURE InvertRgn (rgn: RgnHandle);
  3892.  
  3893.     InvertRgn inverts the pixels enclosed by the specified region: every
  3894. white pixel becomes black and every black pixel becomes white. The
  3895. grafPort's pnPat, pnMode, and bkPat are all ignored; the pen lcoation 
  3896. is not changed.
  3897. \ FillRgn
  3898. 2
  3899. PROCEDURE FillRgn (rgn: RgnHandle; pat: Pattern);
  3900.  
  3901.     FillRgn fills the specified region with the given pattern (in
  3902. patCopy mode). The grafPort's pnPat, pnMode, and bkPat are all ignored;
  3903. the pen location is not changed.
  3904. \ ScrollRect
  3905. 2
  3906. PROCEDURE ScrollRect (r: Rect; dh,dv: INTEGER; updateRgn: RgnHandle);
  3907.  
  3908.     ScrollRect shifts ("scrolls") those bits inside the intersection of
  3909. the specified rectangle, visRgn, clipRgn, portRect, and portBits.bounds.
  3910. The bits are shifted a distance of dh horizontally and dv vertically.
  3911. The positive directions are to the right and down. No other bits are
  3912. affected. Bits that are shifted out of the scroll area are lost; they
  3913. are neither placed outside the area nor saved. The grafPort's
  3914. background pattern bkPat fills the space created by the scroll. In
  3915. addition, updateRgn is changed to the area filled with bkPat (see
  3916. Figure 21).
  3917.  
  3918.     Figure 21 shows that the pen location after a ScrollRect is in a
  3919. different position relative to what was scrolled in the rectangle. The
  3920. entire scrolled item has been moved to different coordinates. To
  3921. restore it to its coordinates before the ScrollRect, you can use the
  3922. SetOrigin procedure. For example, suppose the dstRect here is the
  3923. portRect of the grafPort and its top left corner is at (95,12Ø).
  3924. SetOrigin(1Ø5,115) will offset the coordinate system to compensate for
  3925. the scroll. Since the clipRgn and pen lcoation are not offset, they
  3926. move down and to the left.
  3927. \ CopyBits
  3928. 2
  3929. PROCEDURE CopyBits (srcBits,dstBits: BitMap; srcRect,dstRect: Rect;
  3930.         mode: INTEGER; maskRgn: RgnHandle);
  3931.  
  3932.     CopyBits transfers a bit image between any two bitMaps and clips the
  3933. result to the area specified by the maskRgn parameter. The transfer
  3934. may be performed in any of the eight source transfer modes. The result
  3935. is always clipped to the maskRgn and the boundary rectangle of the
  3936. destination bitMap; if the destination bitMap is the current grafPort's 
  3937. portBits, it is also clipped to the intersection of the grafPort's 
  3938. clipRgn and visRgn. If you do not want to clip to a maskRgn, just pass
  3939. NIL for the maskRgn parameter.
  3940.  
  3941.     The dstRect and maskRgn coordinates are in terms of the
  3942. dstBits.bounds coordinate system, and the src Rect coordinates are in
  3943. terms of the srcBits.bounds coordinates.
  3944.  
  3945.     The bits enclosed by the source rectangle are transferred into the
  3946. destination rectangle according to the rules of the chosen mode. The
  3947. source transfer modes are as follows:
  3948.  
  3949.     srcCopy     srcXor      notSrcCopy  notSrcXor
  3950.     srcOr       srcBic      notSrcOr    notSrcBic
  3951.  
  3952.     The source rectangle is completely aligned with the destination
  3953. rectangles; if the rectangles are of different sizes, the bit image is
  3954. expanded or shrunk as necessary to fit the destination rectangle. For
  3955. example, if the bit image is a circle in a square source rectangle, and
  3956. the destination rectangle is not square, the bit image appears as an
  3957. oval in the destination (see Figure 22).
  3958. \ OpenPicture
  3959. 2
  3960. FUNCTION  OpenPicture (picFrame: Rect) : PicHandle;
  3961.  
  3962.     OpenPicture returns a hendle to a new picture  which has the given
  3963. rectangle as its picture frame, and tells QuickDraw to start saving as
  3964. the picture definition all calls to drawing routines and all picture
  3965. comments (if any).
  3966.  
  3967.     OpenPicture calls HidePen, so no drawing occurs on the screen while
  3968. the picture is open (unless you call ShowPen just after OpenPicture, or
  3969. you called ShowPen previously without balancing it by a call to HidePen)
  3970.  
  3971.     When a picture is open, the current grafPort's picSave field
  3972. contains a handle to information related to the picture definition. If
  3973. you want to temporarily disable the collection of routine calls and
  3974. picture comments, you can save the current value of this field, set the
  3975. field to NIL, and later restore the saved value to resume the picture
  3976. definition.
  3977.  
  3978. (eye)
  3979.     Do not call OpenPicture while another picture is already
  3980.     open.
  3981. \ ClosePicture
  3982. 2
  3983. PROCEDURE ClosePicture;
  3984.  
  3985.     ClosePicture tells QuickDraw to stop saving routine calls and
  3986. picture comments as the definition of the currently open picture. You
  3987. should perform one and only one ClosePicture for every OpenPicture.
  3988. ClosePicture calls ShowPen, balancing the HidePen call made by
  3989. OpenPicture.
  3990. \ PicComment
  3991. 2
  3992. PROCEDURE PicComment (kind,dataSize: INTEGER; dataHandle: QDHandle);
  3993.  
  3994.     PicComment inserts the specified comment into the definition of the
  3995. currently open picture.  Kind identifies the type of comment.
  3996. DataHandle is a handle to additional data if desired, and dataSize is
  3997. the size of that data in bytes. If there is no additional data for the
  3998. comment, dataHandle should be NIL and dataSize should be Ø. The
  3999. application that processes the comment must include a procedure to do
  4000. the processing and store a pointer to the procedure in the data
  4001. structure pointed to by the grafProcs field of the grafPort (see
  4002. "Customizing QuickDraw Operations").
  4003. \ DrawPicture
  4004. 2
  4005. PROCEDURE DrawPicture (myPicture: PicHandle; dstRect: Rect);
  4006.  
  4007.     DrawPicture draws the given picture to scale in dstRect, expanding
  4008. or shrinking it as necessary to align the borders of the picture frame
  4009. with dstRect. DrawPicture passes any picture comments to the procedure
  4010. accessed indirectly through the grafProcs field of the grafPort (see
  4011. PicComment above).
  4012. \ KillPicture
  4013. 2
  4014. PROCEDURE KillPicture (myPicture: PicHandle);
  4015.  
  4016.     KillPicture deallocates space for the picture whose handle is
  4017. supplied, and returns the memory used by the picture to the free memory
  4018. pool. Use this only when you are completely through with a picture.
  4019. \ OpenPoly
  4020. 2
  4021. FUNCTION OpenPoly : PlyHandle;
  4022.  
  4023.     OpenPoly returns a handle to a new polygon and tells QuickDraw to
  4024. start saving the polygon definition as specified by calls to
  4025. line-drawing routines. While a polygon is open, all calls to Line and
  4026. LineTo affect the outline of the polygon. Only the line endpoints
  4027. affect the polygon definition; the pen mode, pattern, and size do not
  4028. affect it. In fact OpenPoly calls HidePen, so no drawing occurs on the
  4029. screen while the polygon is open (unless you call ShowPen just after
  4030. OpenPoly, or you called ShowPen previously without balancing it by a
  4031. call to HidePen).
  4032.  
  4033.     A polygon should consist of a sequence of connected lines. Even
  4034. though the on-screen presentation of a polygon is clipped, the
  4035. definition of a polygon is not; you can define a polygon anywhere on the
  4036. coordinate plane with complete disregard for the location of various
  4037. grafPort entities on that plane.
  4038.  
  4039.     When a polygon is open, the current grafPort's polySave field
  4040. contains a handle to information related to the polygon definition. If
  4041. you want to temprarily disable the polygon definition, you can save the
  4042. current value of this field, set the field to NIL, and later restore the
  4043. saved value to resume the polygon definition.
  4044.  
  4045. (eye)
  4046.     Do not call OpenPoly while another polygon is already
  4047.     open.
  4048. \ ClosePoly
  4049. 2
  4050. PROCEDURE ClosePoly;
  4051.  
  4052.     ClosePoly tells QuickDraw to stop saving the definition of the
  4053. currently open polygon and computes the polyBBox rectangle. You should
  4054. perform one and only one ClosePoly for every OpenPoly. ClosePoly calls
  4055. ShowPen, balancing the HidePen call made by OpenPoly.
  4056.  
  4057.     Here's an example of how to open a polygon, define it as a triangle, 
  4058. close it, and draw it:
  4059.  
  4060.     triPoly := OpenPoly;    {save handle and begin collecting stuff}
  4061.       MoveTo (3ØØ,1ØØ);     { move to first point and }
  4062.       LineTo(4ØØ,2ØØ);      {      form       }
  4063.       LineTo(2ØØ,2ØØ);      {       the           }
  4064.       LineTo(3ØØ,1ØØ);      {     triangle    }
  4065.     ClosePoly;              {stop collecting stuff}
  4066.     FillPoly(triPoly,gray); {draw it on the screen}
  4067.     KillPoly(triPoly);      {we're all done}
  4068. \ KillPoly
  4069. 2
  4070. PROCEDURE KillPoly (poly: PolyHandle);
  4071.  
  4072.     KillPoly deallocates space for the polygon whose handle is supplied,
  4073. and returns the memory used by the polygon to the free memory pool.
  4074. Use this only after you are completely through with a polygon.
  4075. \ OffsetPoly
  4076. 2
  4077. PROCEDURE OffsetPoly (poly: PolyHandle; dh,dv: INTEGER);
  4078.  
  4079.     OffsetPoly moves the polygon on the coordinate plane, a distance of
  4080. dh horizontally and dv vertically. This does not affect the screen
  4081. unless your subsequently call a routine to draw the polygon. If dh and
  4082. dv are positive, the movement is to the right and down; if either is
  4083. negative, the corresponding movement is in the opposite direction. The
  4084. polygon retains its shape and size.
  4085.  
  4086. (hand)
  4087.     OffsetPoly is an especially efficient operation, because
  4088.     the data defining a polygon is stored relative to
  4089.     polyStart and so isn't actually changed by OffsetPoly.
  4090. \ FramePoly
  4091. 2
  4092. PROCEDURE FramePoly (poly: PolyHandle);
  4093.  
  4094.     FramePoly plays back the line-drawing routine calls that define the
  4095. given polygon, using the current grafPort's pen pattern, mode, and 
  4096. size. The pen will hang below and to the right of each point on the
  4097. boundary of the polygon; thus, the polygon drawn will extend beyond the
  4098. right and bottom edges of poly^^.polyBBox by the pen width and pen
  4099. height, respectively. All other graphic operations occur strictly
  4100. within the boundary of the polygon, as for other shapes. You can see
  4101. this difference in Figure 23, where each of the polygons is shown with
  4102. its polyBBox.
  4103.  
  4104.     If a polygon is open and being formed, FramePoly affects the outline
  4105. of the polygon just as if the line-drawing routines themselves had been
  4106. called. If a region is open and being formed, the outside outline of
  4107. the polygon being framed is mathematically added to the region's
  4108. boundary.
  4109. \ PaintPoly
  4110. 2
  4111. PROCEDURE PaintPoly (poly: PolyHandle);
  4112.  
  4113.     PaintPoly paints the specified polygon with the current grafPort's
  4114. pen pattern and pen mode. The polygon on the bitMap is filled with the
  4115. pnPat, according to the pattern transfer mode specified by pnMode. The
  4116. pen location is not changed by this procedure.
  4117. \ ErasePoly
  4118. 2
  4119. PROCEDURE ErasePoly (poly: PolyHandle);
  4120.  
  4121.     ErasePoly paints the specified polygon with the current grafPort's 
  4122. background pattern bkPat (in patCopy mode). The pnPat and pnMode are
  4123. ignored; the pen location is not changed.
  4124. \ InvertPoly
  4125. 2
  4126. PROCEDURE InvertPoly (poly: PolyHandle);
  4127.  
  4128.     InvertPoly inverts the pixels enclosed by the specified polygon:
  4129. every white pixel becomes black and every black pixel becomes white. The
  4130. grafPort's pnPat, pnMode, and bkPat are all ignored; the pen location
  4131. is not changed.
  4132. \ FillPoly
  4133. 2
  4134. PROCEDURE FillPoly (poly: PolyHandle; pat: Pattern);
  4135.  
  4136.     FillPoly fills the specified polygon with the given pattern (in
  4137. patCopy mode.)  The grafPort's pnPat, pnMode, and bkPat are all ignored;
  4138. the pen location is not changed.
  4139. \ AddPt
  4140. 2
  4141. PROCEDURE AddPt (srcPt: Point; VAR dstPt: Point);
  4142.  
  4143.     AddPt adds the coordinates of srcPt to the coordinates of dstPt, and
  4144. returns the result in dstPt.
  4145. \ SubPt
  4146. 2
  4147. PROCEDURE SubPt (srcPt: Point; VAR dstPt: Point);
  4148.  
  4149.     SubPt subtracts the coordinates of srcPt from the coordinates of
  4150. dstPt, and returns the result in dstPt.
  4151. \ SetPt
  4152. 2
  4153. PROCEDURE SetPt (VAR pt: Point; h,v: INTEGER);
  4154.  
  4155.     SetPt assigns two integer coordinates to a variable of type Point.
  4156. \ EqualPt
  4157. 2
  4158. FUNCTION EqualPt (ptA,ptB: Point) : BOOLEAN;
  4159.  
  4160.     EqualPt compares the two points and returns true if they are equal
  4161. or FALSE if not.
  4162. \ LocalToGlobal
  4163. 2
  4164. PROCEDURE LocalToGlobal (VAR pt: Point);
  4165.  
  4166.     LocalToGlobal converts the given point from the current grafPort's
  4167. local coordinate system into a global coordinate system with the origin
  4168. (Ø,Ø) at the top left corner of the port's bit image (such as the 
  4169. screen). This global point can then be compared to other global
  4170. points, or be changed into the local coordinates of another grafPort.
  4171.  
  4172.     Since a rectangle is defined by two points, you can convert a
  4173. rectangle into global coordinates by performing two LocalToGlobal calls,
  4174. You can also convert a rectangle, region, or polygon into global
  4175. coordinates by calling OffsetRect, OffsetRgn, or OffsetPoly. For
  4176. examples, see GlobalToLocal below.
  4177. \ GlobalToLocal
  4178. 2
  4179. PROCEDURE GlobalToLocal (VAR pt: Point);
  4180.  
  4181.     GlobalToLocal takes a point expressed in global coordinates (with
  4182. the top left corner of the bitMap as coordinate (Ø,Ø)) and converts it
  4183. into the local coordinates of the current grafPort. The global point
  4184. can be obtained with the LocalToGlobal call (see above). For example,
  4185. suppose a game draws a "ball" within a rectangle named ballRect, defined
  4186. in the grafPort named gamePort (as illustrated below in Figure 24). If
  4187. you want to draw that ball in the grafPort named selectPort, you can
  4188. calculate the ball's selectPort coordinates like this:
  4189.  
  4190.     SetPort(gamePort);                  {start in origin port}
  4191.     selectBall:= ballRect;              {make a copy to be moved}
  4192.     LocalToGlobal(selectBall.topLeft);  {put both corners into }
  4193.     LocalToGlobal(selectBall.botRight); {  global coordinates  }
  4194.  
  4195.     SetPort(selectPort);                {switch to destination port}
  4196.     GlobalToLocal(selectBall.topLeft);  {put both corners into     }
  4197.     GlobalToLocal(selectBall.botRight); {  these local coordinates }
  4198.     FillOval(selectBall,ballColor);     {now you have the ball!}
  4199.  
  4200.     You can see from Figure 24 that LocalToGlobal and GlobalToLocal
  4201. simply offset the coordinates of the rectangle by the coordinates of the
  4202. top left corner of the local grafPort's boundary rectangle. You could
  4203. also do this with OffsetRect. In fact the way to convert regions and
  4204. polygons from one coordinate system to another is with OffsetRgn or
  4205. OffsetPoly rather than LocalToGlobal and GlobalToLocal. For example,
  4206. if myRgn were a region enclosed by a rectangle having the same
  4207. coordinates as ballRect in gamePort, you could convert the region to
  4208. global coordinates with
  4209.  
  4210.     OffsetRgn(myRgn, -2Ø, -4Ø);
  4211.  
  4212. and then convert it to the coordinates of the selectPort grafPort with
  4213.  
  4214.     OffsetRgn(myRgn, l5, -3Ø);
  4215. \ Random
  4216. 2
  4217. FUNCTION Random : INTEGR;
  4218.  
  4219.     This function returns an integer, uniformly distributedpseudo-
  4220. random, in the range from -32768 through 32767. The value returned
  4221. depends on the global variable randSeed, which InitGraf initializes to
  4222. 1; you can start the sequence over again from where it began by
  4223. resetting randSeed to 1.
  4224. \ GetPixel
  4225. 2
  4226. FUNCTION GetPixel (h,v: INTEGER) : BOOLEAN;
  4227.  
  4228.     GetPixel looks at the pixel associated with the given coordinate
  4229. point and returns TRUE if it is black or FALSE if it is white. The
  4230. selected pixel is immediately below and to the right of the point whose
  4231. coordinates are given in h and v, in the local coordinates of the
  4232. current grafPort. There is no guarantee that the specified pixel
  4233. actually belongs to the port, however; it may have been drawn by a port
  4234. overlapping the current one. To see if the point indeed belongs to the
  4235. current port, perform a PtInRgn(pt,thePort^.visRgn).
  4236. \ StuffHex
  4237. 2
  4238. PROCEDURE StuffHex (thingPtr: QDPtr; s: Str255);
  4239.  
  4240.     StuffHex pokes bits (expressed as a string of hexadecimal digits)
  4241. into any data structure. This is a good way to create cursors, patterns,
  4242. or bit images to be "stamped" onto the screen with CopyBits. For
  4243. example,
  4244.  
  4245.     StuffHex(@stripes,'Ø1Ø2Ø4Ø81Ø2Ø4Ø8Ø')
  4246.  
  4247. places a striped pattern into the pattern variable stripes.
  4248.  
  4249. (eye)
  4250.     There is no range checking on the size of the destination
  4251.     variable. It's easy to overrun the variable and destroy 
  4252.     something if you don't know what you're doing.
  4253. \ ScalePt
  4254. 2
  4255. PROCEDURE ScalePt (VAR pt: Point; srcRect,dstRect: Rect);
  4256.  
  4257.     A width and height are passed in pt; the horizontal component of pt
  4258. is the width, and the vertical component of pt is the height. ScalePt
  4259. scales these measurements as follows and returns the result in pt: it
  4260. multiplies the given width by the ratio of dstRect's width to srcRect's
  4261. width, and multiplies the given height by the ratio of dstRec's height 
  4262. to srcRect's height. In Figure 25, where dstRect's width is twice
  4263. srcRect's width and its height is three times srcRect's height, the pen
  4264. width is scaled from 3 to 6 and the pen height is scaled from 2 to 6.
  4265. \ MapPt
  4266. 2
  4267. PROCEDURE MapPt (VAR pt: Point; srcRect,dstRect: Rect);
  4268.  
  4269.     Given a point within srcRect, MapPt maps it to a similarly located
  4270. point within dstRect (that is, to where it would fall if it were part
  4271. of a drawing being expanded or shrunk to fit dstRect). The result is
  4272. returned in pt. A corner point of srcRect would be mapped to the
  4273. corresponding corner point of dstRect, and the center of srcRect to the
  4274. center of dstRect. In Figure 25 above, the point (3.2) in srcRect is
  4275. mapped to (l8,7) in dstRect. FromRect and dstRect may overlap, and pt
  4276. need not actually be within srcRect.
  4277.  
  4278. (eye)
  4279.     Remember, if you are going to draw inside the rectangle
  4280.     in dstRect, you will probably also want to scale the pen
  4281.     size accordingly with ScalePt.
  4282. \ MapRect
  4283. 2
  4284. PROCEDURE MapRect (VAR r: Rect; srcRect,dstRect: Rect);
  4285.  
  4286.     Given a rectangle within srcRect, MapRect maps it to a similarly
  4287. located rectangle within dstRect by calling MapPt to map the top left
  4288. and bottom right corners of the rectangle. The result is returned in
  4289. r.
  4290. \ MapRgn
  4291. 2
  4292. PROCEDURE MapRgn (rgn: RgnHandle; srcRect: Rect);
  4293.  
  4294.     Given a region within srcRec, MapRgn maps it to a similarly located
  4295. region within dstRect by calling MapPt to map all the points in the
  4296. region.
  4297. \ MapPoly
  4298. 2
  4299. PROCEDURE MapPoly (poly: PolyHandle; srcRect,dstRect: Rect);
  4300.  
  4301.     Given a polygon within srcRect, MapPoly maps it to a similarly
  4302. located polygon within dstRect by calling MapPt to map all the pointsthat
  4303. define the polygon.
  4304. \ SetStdProcs
  4305. 2
  4306. PROCEDURE SetStdProcs (VAR procs: QDProcs);
  4307.  
  4308.     This procedure sets all the fields of the given QDProcs record to
  4309. point to the standard low-level routines. You can then change the ones
  4310. you wish to point to your own routines. For example, if your procedure
  4311. that processes picture comments is named MyComments, you will store
  4312. @MyComments in the commentProc field of the QD Procs record.
  4313.  
  4314.     The routines you install must of course have the same calling
  4315. sequences as the standard routines, which are described below. The
  4316. standard drawing routines tell which graphic operation to perform from a
  4317. parameter of type GrafVerb.
  4318.  
  4319.     TYPE GrafVerb = (frame, paint, erase, invert, fill);
  4320.  
  4321.     When the grafVerb is fill, the pattern to use when filling is passed
  4322. in the fillPat field of the grafPort.
  4323. \ StdText
  4324. 2
  4325. PROCEDURE StdText (byteCount: INTEGER; textBuf: QDPtr; numer,denom:
  4326.         INTEGER);
  4327.  
  4328.     StdText is the standard low-level routine for drawing text. It draws
  4329. text from the arbitrary structure in memory specified by textBuf,
  4330. starting from the first byte and continuing for byteCount bytes. Numer
  4331. and denom specify the scaling, if any:  numer.v over denom.v gives the
  4332. vertical scaling, and numer.h over denom.h gives the horizontal
  4333. scaling.
  4334. \ StdLine
  4335. 2
  4336. PROCEDURE StdLine (newPt: Point);
  4337.  
  4338.     StdLine is the standard low-level routine for drawing a line. It
  4339. draws a line from the current pen location to the location specified (in
  4340. local coordinates) by newPt.
  4341. \ StdRect
  4342. 2
  4343. PROCEDURE StdRect (verb; r: Rect);
  4344.  
  4345.     StdRect is the standard low-level routine for drawing a rectangle.
  4346. It draws the given rectangle according to the specified grafVerb.
  4347. \ StdRRect
  4348. 2
  4349. PROCEDURE StdRRect (verb: GrafVerb; r: Rect; ovalwidth,ovalHeight:
  4350.                     INTEGER);
  4351.  
  4352.     StdRrect is the standard low-level routine for drawing a rounded-
  4353. corner rectangle. It draws the given rounded-corner rectangle according
  4354. to the specified grafVerb. OvalWidth and ovalHeight specify the
  4355. diameters of curvature for the corners.
  4356. \ StdOval
  4357. 2
  4358. PROCEDURE StdOval (verb: GrafVerb; r: Rect);
  4359.  
  4360.     StdOval is the standard low-level routine for drawing an oval. It
  4361. draws an oval inside the given rectangle according to the specified
  4362. grafVerb.
  4363. \ StdArc
  4364. 2
  4365. PROCEDURE StdArc (verb: GrafVerb; r: Rect; startAngle,arcAngle:
  4366.                     INTEGER);
  4367.  
  4368.     StdArc is the standard low-level routine for drawing an arc or a
  4369. wedge. It draws an arc or wedge of the oval that fits inside the given
  4370. rectangle. The grafVerb specifies the graphic operation; it it's the 
  4371. frame operation, an arc is drawn; otherwise, a wedge is drawn.
  4372. \ StdPoly
  4373. 2
  4374. PROCEDURE StdPoly (verb: GrafVerb; poly: PolyHandle);
  4375.  
  4376.     StdPoly is the standard low-level routine for drawing a polygon. It
  4377. draws the given polygon according to the specified grafVerb.
  4378. \ StdRgn
  4379. 2
  4380. PROCEDURE StdRgn (verb: GrafVerb; rgn: RgnHandle);
  4381.  
  4382.     StdRgn is the standard low-level routine for drawing a region. It
  4383. draws the given region according to the specified grafVerb.
  4384. \ StdBits
  4385. 2
  4386. PROCEDURE StdBits (VAR srcBits: BitMap; VAR srcRect,dstRect: Rect;
  4387.                     mode: INTEGER; maskRgn: RgnHandle);
  4388.  
  4389.     StdBits is the standard low-level routine for doing bit transfer.It
  4390. transfers a bit image between the given bitMap and thePort^.portBits,
  4391. just as if CopyBits were called with the same parameters and with a
  4392. destination bitMap equal to thePort^.portBits.
  4393. \ StdComment
  4394. 2
  4395. PROCEDURE StdComment (kind,dataSize: INTEGER; dataHandle: QDHandle);
  4396.  
  4397.     StdComment is the standard low-level routine for processing a
  4398. picture comment. Kind identifies the type of comment. DataHandle is a
  4399. handle to additional data, and dataSize is the size of that data in
  4400. bytes. If there is no additional data for the command, dataHandle will
  4401. be NIL and dataSize will be Ø. StdComment simply ignores the comment.
  4402. \ StdTxMeas
  4403. 2
  4404. FUNCTION StdTxMeas (byteCount: INTEGER; textBuf: QDPtr; VAR
  4405.                     numer,denom: Point; VAR info: FontInfo) : INTEGER;
  4406.  
  4407.     StdTxMeas is the standard low-level routine for measung text width.
  4408. It returns the width of the text stored in the arbitrary structure in
  4409. memory specified by textBuf, starting with the first byte and
  4410. continuing for byteCount bytes. Numer and denom specify the scaling as
  4411. in the StdText procedure; note that StdTxMeas may change them.
  4412. \ StdGetPic
  4413. 2
  4414. PROCEDURE StdGetPic (dataPtr: QDPtr; byteCount: INTEGER);
  4415.  
  4416.     StdGetPic is the standard low-level routine for retrieving
  4417. information from the definition of a picture. It retrieves the next
  4418. byteCount bytes from the definition of the currently open picture and
  4419. stores them in the data structure pointed to by dataPtr.
  4420. \ StdPutPic
  4421. 2
  4422. PROCEDURE StdPutPic (dataPtr: QdPtr; byteCount: INTEGER);
  4423.  
  4424.     StdPutPic is the standard low-level routine for saving information
  4425. as the definition of a picture. It saves as the definition of the
  4426. currently open picture the drawing commands stored in the data
  4427. structure pointed to by dataPtr, starting with the first byte and
  4428. continuing for the next byteCount bytes.
  4429. \ SeedFill
  4430. 2
  4431. PROCEDURE SeedFill (srcPtr,dstPtr: Ptr; srcRow, dstRow, height,
  4432.                     words,seedH,seedV: INTEGER);
  4433.  
  4434.     Given a source bit image, SeedFill computes a destination bit image
  4435. with 1’s only in the pixels where paint can leak from the starting
  4436. seed point, like the MacPaint paint-bucket tool. SeedH and seedV
  4437. specify horizontal and vertical offsets, in pixels, from the beginning
  4438. of the data pointed to by dstPtr, determining how far into the
  4439. destination bit image filling should begin. Calls to SeedFill are not
  4440. clipped to the current port and are not stored into QuickDraw pictures.
  4441. \ CalcMask
  4442. 2
  4443. PROCEDURE CalcMask (srcPtr,dstPtr: Ptr; srcRow, dstRow, height,
  4444.                     words: INTEGER);
  4445.  
  4446.     Given a source bit image, CalcMask computes a destination bit image
  4447. with 1’s only in the pixels where paint could not leak from any of
  4448. the outer edges, like the MacPaint lasso tool. Calls to CalcMask are
  4449. not clipped to the current port and are not stored into QuickDraw
  4450. pictures.
  4451. \ CopyMask
  4452. 2
  4453. PROCEDURE CopyMask (srcBits,maskBits,dstBits: BitMap; srcRect,
  4454.                     maskRect,dstRect: Rect);
  4455.  
  4456.     CopyMask is a new version of the CopyBits procedure; it transfers a
  4457. bit image from the source bitmap to the destination bitmap only where
  4458. the corresponding bit of the mask rectangle is a 1. (Note that
  4459. the mask is specified as a rectangle instead of as a handle to a region.)  It can be used along with CalcMask to implement the lasso copy as in MacPaint; it’s also useful for drawing icons. CopyMask doesn’t check for overlap between the source and destina
  4460. \ MeasureText
  4461. 2
  4462. PROCEDURE MeasureText (count: INTEGER; textAddr,charLocs: Ptr);
  4463.  
  4464.     This procedure is designed to improve performance in specialized
  4465. applications such as word processors by providing an array version of
  4466. the TextWidth function; it’s like calling TextWidth repeatedly for a
  4467. given set of characters. TextAddr points to an arbitrary piece of text
  4468. in memory, and count specifies how many characters are to be measured.
  4469.  
  4470.     MeasureText moves along the string and, for each character, computes
  4471. the distance from TextAddr to the right edge of the character.
  4472. CharLocs should point to an array of count + 1 integers. Upon return,
  4473. the first element in the array will always contain 0; the other elements
  4474. will contain pixel positions on the screen for all of the specified
  4475. characters.
  4476.  
  4477. Note:   MeasureText only works with text displayed on the screen;
  4478.         since it doesn’t go through the QuickDraw procedure StdText, it
  4479.         can’t be used to measure text to be printed.
  4480.  
  4481. \ GetMaskTable
  4482. 2
  4483.     The function GetMaskTable, accessible only from assembly language,
  4484. returns in register A0 a pointer to a ROM table containing the following
  4485. useful masks:
  4486.  
  4487. .WORD $0000,$8000,$C000,$E000   ;Table of 16 right masks
  4488. .WORD $F000,$F800,$FC00,$FE00
  4489. .WORD $FF00,$FF80,$FFC0,$FFE0
  4490. .WORD $FFF0,$FFF8,$FFFC,$FFFE
  4491.  
  4492. .WORD $FFFF,$7FFF,$3FFF,$1FFF   ;Table of 16 left masks
  4493. .WORD $0FFF,$07FF,$03FF,$01FF
  4494. .WORD $00FF,$007F,$003F,$001F
  4495. .WORD $000F,$0007,$0003,$0001
  4496.  
  4497. .WORD $8000,$4000,$2000,$1000   ;Table of 16 bit masks
  4498. .WORD $0800,$0400,$0200,$0100
  4499. .WORD $0080,$0040,$0020,$0010
  4500. .WORD $0008,$0004,$0002,$0001
  4501.  
  4502. _GetMaskTable : Macro Name.
  4503. \ InitFonts
  4504. 3
  4505. PROCEDURE InitFonts;
  4506.  
  4507.     InitFonts initializes the Font Manager. If the system font isn't
  4508. already in memory, InitFonts reads it into memory. Call this procedure
  4509. once before all other Font Manager routines or any Toolbox routine that
  4510. will call the Font Manager.
  4511. \ GetFontName
  4512. 3
  4513. PROCEDURE GetFontName (fontNum: INTEGER; VAR theName: Str255);
  4514.  
  4515.     GetFontName returns in theName the name of the font having the font
  4516. number fontNum. If there's no such font, GetFontName returns the empty
  4517. string.
  4518. \ GetFNum
  4519. 3
  4520. PROCEDURE GetFNum (fontName: Str255; VAR theNum: INTEGER);
  4521.  
  4522.     GetFNum returns in theNum the font number for the font having the
  4523. given fontName. If there's no such fone getFNum returns Ø.
  4524. \ RealFont
  4525. 3
  4526. FUNCTION RealFont (fontNum: INTEGER; size: INTEGER) : BOOLEAN;
  4527.  
  4528.     RealFont returns TRUE if the font having the font number fontNum is
  4529. available in the given size in a resource file, or FALSE if the font
  4530. has to be scaled to that size.
  4531. \ SetFontLock
  4532. 3
  4533. PROCEDURE SetFontLock (lockFlag: BOOLEAN);
  4534.  
  4535.     SetFontLock applies to the font in which text was most recently
  4536. drawn; it makes the font unpurgeable if lockFlag is TRUE or purgeable if
  4537. lockFlag is FALSE. Since fonts are normally purgeable, this procedure
  4538. is useful for making a font temporarily unpurgeable.
  4539. \ SwapFont
  4540. 3
  4541. FUNCTION SwapFont (inRec: FMInput) : FMOutPtr;
  4542.  
  4543.     SwapFont returns a pointer to an FMOutput record containing the
  4544. size, style, and other information about an adapted version of the font
  4545. requested in the given FMInput record. (FMInput and FMOutput records
  4546. are explained in the following section.)  SwapFont is called by
  4547. QuickDraw every time a QuickDraw routine that does anything with text
  4548. is used. If you want to call SwapFont yourself, you must build an
  4549. FMInput record and then use the returned pointer to access the
  4550. resulting FMOutput record.
  4551. \ FontMetrics
  4552. 3
  4553. PROCEDURE FontMetrics (VAR theMetrics: FMetricRec);
  4554.  
  4555.     FontMetrics is similar to the QuickDraw procedure GetFontInfo except
  4556. that it returns fixed-point values for greater accuracy in
  4557. high-resolution printing.
  4558.  
  4559. The FMetricRec data structure is defined as follows:
  4560.  
  4561. TYPE FMetricRec = RECORD
  4562.          ascent:    Fixed;  {ascent}
  4563.          descent:   Fixed;  {descent}
  4564.          leading:   Fixed;  {leading}
  4565.          widMax:    Fixed;  {maximum character width}
  4566.          wTabHandle:    Handle; {handle to global width table}
  4567.        END;
  4568.  
  4569.     Ascent, descent, leading, and widMax are identical in function to
  4570. their counterparts in GetFontInfo. WTabHandle is a handle to the
  4571. global width table (described below).
  4572.  
  4573. \ SetFractEnable
  4574. 3
  4575. PROCEDURE SetFractEnable (fractEnable: BOOLEAN)   [Not in ROM]
  4576.  
  4577.     SetFractEnable lets you enable or disable fractional character
  4578. widths. If fractEnable is TRUE, fractional character widths are enabled;
  4579. if it’s FALSE, the Font Manager uses integer widths. To ensure
  4580. compatibility with existing applications, fractional character widths
  4581. are disabled by default.
  4582. ___________________________________________________________________
  4583.  
  4584. Assembly-language note:  From assembly language, you can change the
  4585. value of the global variable FractEnable.
  4586. ___________________________________________________________________
  4587. \ SetFScaleDisable
  4588. 3
  4589. PROCEDURE SetFScaleDisable (fontScaleDisable: BOOLEAN);
  4590.  
  4591.     SetFScaleDisable lets you disable or enable font scaling.
  4592. If fontScaleDisable is TRUE, font scaling is disabled and
  4593. the Font Manager returns an unscaled font with more space around
  4594. the characters; if it’s FALSE, the Font Manager scales fonts.
  4595. To ensure compatibility with existing applications, the Font Manager
  4596. defaults to scaling fonts.
  4597.  
  4598.     ______________________________________________________________
  4599.     Assembly-language note:  All programmers should use the
  4600.     SetFScaleDisable procedure to disable and enable font scaling.
  4601.     In particular, setting the global variable FScaleDisable is
  4602.     insufficient.
  4603.     ______________________________________________________________
  4604. \ GetNextEvent
  4605. 4
  4606. FUNCTION GetNextEvent (eventMask: INTEGER; VAR theEvent: EventRecord)
  4607.                         : BOOLEAN;
  4608.  
  4609.     GetNextEvent returns the next available event of a specified type or
  4610. types and, if the event is in the event queue, removes it from the
  4611. queue. The event is returned as the value of the parameter theEvent.
  4612. The eventMask parameter specifies which event types are of interest.
  4613. GetNextEvent returns the next available event of any type designated by
  4614. the mask, subject to the priority rules discussed above under "Priority
  4615. of Events". If no event of any of the designated types is available,
  4616. GetNextEvent returns a null event.
  4617.  
  4618. (note)
  4619.     Events in the queue that aren't designated in the mask 
  4620.     are kept in the queue; if you want to remove them, you
  4621.     can do so by calling the Operating System Event Manager
  4622.     procedure FlushEvents.
  4623.  
  4624.     Before reporting an event to your application, GetNextEvent first
  4625. calls the Desk Manager function System Event to see whether the system
  4626. wants to intercept and respond to the event. If so, or if the event
  4627. being reported is a null event, GetNextEvent returns a function result
  4628. of FALSE; a function result of TRUE means that your application should
  4629. handle the event itself. The Desk Manager intercepts the following
  4630. events:
  4631.  
  4632.     - activate and update events directed to a desk accessory
  4633.  
  4634.     - keyboard events if the currently active window belongs to a desk
  4635.       accessory
  4636.  
  4637. (note)
  4638.     In each case, the event is intercepted by the Desk
  4639.     Manager only if the desk accessory can handle that type
  4640.     of event; however, as a rule all desk accessories should
  4641.     be set up to handle activate, update, and keyboard
  4642.     events.
  4643.  
  4644.     The Desk Manager also intercepts disk-inserted events:  It attempts
  4645. to mount the volume on the disk by calling the File Manager function
  4646. MountVol. GetNextEvent will always return TRUE in this case, though,
  4647. so that your application can take any further appropriate action after
  4648. examining the result code returned by MountVol in the event message.
  4649. (See the Desk Manager and File Manager manuals for further details.)
  4650. GetNextEvent returns TRUE for all other non-null events (including all
  4651. mouse-down events, regardless of which window is active), leaving them
  4652. for your application to handle.
  4653.  
  4654.     GetNextEvent also makes the following processing happen, invisible
  4655. to your program:
  4656.  
  4657.    -If the "alarm" is set and the current time is the alarm time, the
  4658.     alarm goes off (a beep followed by blinking the title of the Apple
  4659.     menu). The user can set the alarm with the Alarm Clock desk
  4660.     accessory.
  4661.  
  4662.    -If the user holds down the Command and Shift keys while pressing a
  4663.     numeric key that has a special effect, that effect occurs. The
  4664.     standard such keys are 1 and 2 for ejecting the disk in the
  4665.     internal or external drive, and 3 and 4 for writing a snapshot of
  4666.     the screen to a MacPaint document or to the printer.
  4667.  
  4668.  (note)
  4669.     Advanced programmers can implement their own code to be
  4670.     executed in response to Command-Shift-number combinations
  4671.     (except for Command-Shift-l and 2, which can't be 
  4672.     changed). The code corresponding to a particular number
  4673.     must be a routine having no parameters, stored in a
  4674.     resource whose type is 'FKEY' and whose ID is the number.
  4675.     The system resource file contains code for the numbers 3
  4676.     and 4.
  4677. \ EventAvail
  4678. 4
  4679. FUNCTION EventAvail (eventMask: INTEGER; VAR theEvent: EventRecord) :
  4680.     BOOLEAN;
  4681.  
  4682.     EventAvail works exactly the same as GetNextEvent except that if the
  4683. event is in the event queue, it's left there.
  4684.  
  4685. (note)
  4686.     An event returned by EventAvail will not be accessible
  4687.     later if in the meantime the queue becomes full and the
  4688.     event is discarded from it; since the events discarded
  4689.     are always the oldest ones in the queue, however, this
  4690.     will happen only in an unusually busy environment.
  4691. \ GetMouse
  4692. 4
  4693. PROCEDURE GetMouse (VAR mouseLoc: Point);
  4694.  
  4695.     GetMouse returns the current mouse location in the mouseLoc
  4696. parameter. The location is given in the local coordinate system of the
  4697. current grafPort (which might be, for example, the currently active
  4698. window). Notice that this differs from the mouse location stored in the
  4699. where field of an event record; that location is always in global
  4700. coordinates.
  4701. \ Button
  4702. 4
  4703. FUNCTION Button : BOOLEAN;
  4704.  
  4705.     The Button function returns TRUE if the mouse button is currently
  4706. down, and FALSE if it isn't.
  4707. \ Stilldown
  4708. 4
  4709. FUNCTION StillDown : BOOLEAN;
  4710.  
  4711.     Usually called after a mouse-down event, StillDown tests whether the
  4712. mouse button is still down. It returns TRUE if the button is currently
  4713. down and there are no more mouse events pending in the event queue.
  4714. This is a true test of whether the button is still down from the
  4715. original press--unlike Button (above), which returns TRUE whenever the
  4716. button is currently down, even it ift has been released and pressed
  4717. again since the original mouse-down event.
  4718. \ WaitMouseUp
  4719. 4
  4720. FUNCTION WaitMouseUp ) BOOLEAN;
  4721.  
  4722.     WaitMouseUp works exactly the same as StillDown (above), excent that
  4723. if the button is not still down from the original press, WaitMouseUp
  4724. removes the preceding mouse-up event before returning FALSE. If, for
  4725. instance, your application attaches some special significance both to
  4726. mouse double-clicks and to mouse-up events, this function would allow
  4727. your application to recognize a double-click without being confused by
  4728. the intervening mouse-up.
  4729. \ GetKeys
  4730. 4
  4731. PROCEDUREGetKeys (VAR theKeys: KeyMap);
  4732.  
  4733.     GetKeys reads the current state of the keyboard (and keypad, if any)
  4734. and returns it in the form of a keyMap:
  4735.  
  4736.     TYPE KeyMap = PACKED ARRAY [Ø..127] OF BOOLEAN;
  4737.  
  4738.     Each key on the keyboard or keypad corresponds to an element in the
  4739. keyMap. The index into the keyMap for a particular key is the same as
  4740. the key code for that key. (The key codes are shown in Figure 3
  4741. above.)  The keyMap element is TRUE if the corresponding key is down
  4742. and FALSE if it isn't. The maximum number of keys that can be down 
  4743. simultaneously is two character keys plus any combination of the four
  4744. modifier keys.
  4745. \ TickCount
  4746. 4
  4747. FUNCTION TickCount : LONGINT;
  4748.  
  4749.     TickCount returns the current number of ticks (sixtieths of a
  4750. second) since the system was last started up.
  4751. \ GetDblTime
  4752. 4
  4753. FUNCTION GetDblTime : LONGINT; [No trap macro]
  4754.  
  4755.     GetDblTime returns the suggested maximum difference (in ticks) that
  4756. should exist between the times of a mouse-up event and a mouse-down
  4757. event for those two mouse clicks to be considered a double-click. The
  4758. user can adjust this value by means of the Control Panel desk
  4759. accessory.
  4760. \ GetCaretTime
  4761. 4
  4762. FUNCTION GetCaretTime : LONGINT; [No trap macro]
  4763.  
  4764.     GetCareTime returns the time (in ticks) between blinks of the
  4765. "caret" (usually a vertical bar) marking an insertion point in editable
  4766. text. If you aren't using TextEdit, you'll need to cause the caret to
  4767. blink yourself; on every pass through your program's main event loop,
  4768. you should check this value against the elapsed time since the last
  4769. blink of the caret. The user can adjust this value by means of the
  4770. Control Panel desk accessory.
  4771. \ InitWindows
  4772. 5
  4773. PROCEDURE InitWindows;
  4774.  
  4775.     InitWindows initializes the Window Manager. It creates the Window
  4776. Manager port; you can get a pointer to this port with the GetWMgrPort
  4777. procedure. InitWindows draws the desktop and the (empty menu bar.
  4778. Call this procedure once berore all other Window Manager routines.
  4779.  
  4780. (note)
  4781.     InitWindows creates the Window Manager port as a
  4782.     nonrelocatable block in the application heap. For
  4783.     information on how this may affect your application's use
  4784.     of memory, see the Memory Manager manual. ***(A section
  4785.     on how to survive with limited memory will be added to
  4786.     that manual.) ***
  4787. \ GetWMgrPort
  4788. 5
  4789. PROCEDURE GetWMgrPort (VAR wPort:  GrafPtr);
  4790.  
  4791.     GetWMgrPort returns in wPort a pointer to the Window Manager port.
  4792. \ NewWindow
  4793. 5
  4794. FUNCTION NewWindow (wStorage: Ptr; boundsRect: Rect; title: Str255;
  4795.                     visible: BOOLEAN; procID: Integer;behind: WindowPtr;
  4796.                     goAway Flag: BOOLEAN; refCon: LongInt) : WindowPtr;
  4797.  
  4798.     NewWindow creates a window as specified by its parameters, adds it
  4799. to the window list, and returns a windowPtr to the new window. It
  4800. allocates space for the structure and content regions of the window and
  4801. asks the window definition function to calculate those regions.
  4802.  
  4803.     WStorage is a pointer to where to store the window record. For
  4804. example, if you've declared the variable wRecord of type WindowRecord,
  4805. you can pass @wRecord as the first parameter to NewWindow. If you pass
  4806. NIL for wStorage, the window record will be allocated on the heap; in
  4807. that case, though, the record will be nonrelocatable, and so you risk
  4808. ending up with a fragmented heap. You should therefore not pass NIL
  4809. for wStorage unless your program has an unusually large amount of
  4810. memory available or has been set up to dispose of windows dynamically.
  4811. Even then, you should avoid passing NIL for wStorage if there's no 
  4812. limit to the number of windows that your application can open. ***
  4813. (Some of this may be moved to the Memory Manager manual when that
  4814. manual is updated to have a section on how to survive with limited
  4815. memory.) ***
  4816.  
  4817.     BoundsRect, a rectangle given in global coordinates, determines the
  4818. window's size and location. It becomes the portRect of the window's
  4819. grafPort; note, however, that the portRect is in local coordinates.
  4820. New Window makes the QuickDraw call SetOrigin(Ø,Ø), so that the top left
  4821. corner of the portRect will be (Ø,Ø).
  4822.  
  4823. (note)
  4824.     The bitMap, pen pattern, and other characteristics of the
  4825.     window's grafPort are the same as the default values set
  4826.     by the OpenPort procedure in QuickDraw, except for the
  4827.     character font, which is set to the application font
  4828.     rather than the system font. Note, however, that the
  4829.     SetOrigin(Ø,Ø) call changes the coordinates of the
  4830.     grafPort's portBits.bounds and visRgn as well as its 
  4831.     PortRect.
  4832.  
  4833.     Title is the window's title. If the title of a document window is 
  4834. longer than will fit in the title bar, only as much of the beginning of
  4835. the title as will fit is displayed.
  4836.  
  4837.     If the visible parameter is TRUE, NewWindow draws the window. First
  4838. it calls the window definition function to draw the window frame; if
  4839. goAwayFlag is also TRUE and the window is frontmost (as specified by
  4840. the behind parameter, below), it draws a go-away region in the frame.
  4841. Then it generates an update event for the entire window contents.
  4842.  
  4843.     ProcID is the window definition ID, which leads to the window
  4844. definition function for this type of window. The window definition IDs
  4845. for the predefined types of windows are listed above under "Windows and 
  4846. Resources". Window definition IDs for windows of your own design are 
  4847. discussed later under "Defining Your Own Windows".
  4848.  
  4849.     The behind parameter determines the window's plane. The new window
  4850. is inserted in back of the window pointed to by this parameter. To put
  4851. the new window behind all other windows, use behind=NIL. To place it
  4852. in front of all other windows, use behind=POINTER(-1); in this case,
  4853. NewWindow will unhighlight the previously active window, highlight the
  4854. window being created, and generate appropriate activate events.
  4855.  
  4856.     RefCon is the window's reference value, set and used only by your 
  4857. application.
  4858.  
  4859.     NewWindow also sets the window class in the window record to
  4860. indicate that the window was created directly by the application.
  4861. \ GetNewWindow
  4862. 5
  4863. FUNCTION GetNewWindow (ID: INTEGER; wStorage: Ptr; behind:
  4864.                         WindowPtr) : WindowPtr;
  4865.  
  4866.     Like NewWindow (above), GetNewWindow creates a window as specified
  4867. by its parameters, adds it to the window list, and returns a windowPtr
  4868. to the new window. The only difference between the two functions is
  4869. that instead of having the parameters boundsRect, title, visible,
  4870. procId, goAwayFlag, and refCon, GetNewWindow has a single windowID
  4871. parameter, where windowID is the resource ID of a window template that
  4872. supplies the same information as those parameters. The wStorage and
  4873. behind parameters of GetNewWindow have the same meaning as in NewWindow.
  4874. \ CloseWindow
  4875. 5
  4876. PROCEDURE CloseWindow (theWindow: WindowPtr);
  4877.  
  4878.     CloseWindow removes the given window from the screen and deletes it
  4879. from the window list. It releases the memory occupied by all data
  4880. structures associated with the window, but not the memory taken up by
  4881. the window record itself. Call this procedure when you're done with a 
  4882. window if you supplied NewWindow or GetNewWindow a pointer to the
  4883. window storage (in the wStorage parameter) when you created the window.
  4884.  
  4885.     Any update events for the window are discarded. If the window was
  4886. the frontmost window and there was another window behind it, the latter
  4887. window is highlighted and an appropriate activate event is generated.
  4888. \ DisposeWindow
  4889. 5
  4890. PROCEDURE DisposeWindow (theWindow: WindowPtr);
  4891.  
  4892.     DisposeWindow calls CloseWindow (above) and then releases the memory
  4893. occupied by the window record. Call this procedure when you're done 
  4894. with a window if you let the window record be allocated on the heap
  4895. when you created the window (by passing NIL as the wStorage parameter
  4896. to NewWindow or GetNewWindow).
  4897. \ SetWTitle
  4898. 5
  4899. PROCEDURE SetWTitle (theWindow: WindowPtr; title: Str255);
  4900.  
  4901.     SetWTitle sets the Window's title to the given string, performing
  4902. any necessary redrawing of the window frame.
  4903. \ GetWTitle
  4904. 5
  4905. PROCEDURE GetWTitle (theWindow: WindowPtr; VAR title: Str255);
  4906.  
  4907.     GetWTitle returns theWindow's title as the value of the title
  4908. parameter.
  4909. \ SelectWindow
  4910. 5
  4911. PROCEDURE SelectWindow (theWindow: WindowPtr);
  4912.  
  4913.     SelectWindow makes theWindow the active window as follows:  it
  4914. unhighlights the previously active window, brings theWindow in front of
  4915. all other windows, highlights theWindow, and generates the appropriate
  4916. activate events. Call this procedure if there's a mouse-down event in 
  4917. the content region of an inactive window.
  4918. \ HideWindow
  4919. PROCEDURE HideWindow (theWindow: WindowPtr);
  4920.  
  4921.     HideWindow makes theWindow invisible. If theWindow is the frontmost
  4922. window and there's a window behind it, HideWindow also unhighlights 
  4923. theWindow, brings the window behind it to the front, highlights that
  4924. window, and generates appropriate activate events (se Figure 6). If
  4925. theWindow is already invisible, HideWindow has no effect.
  4926. \ ShowWindow
  4927. 5
  4928. PROCEDURE ShowWindow (theWindow: WindowPtr);
  4929.  
  4930.     ShowWindow makes theWindow visible. It does not change the front-to-
  4931. back ordering of the windows. Remember that if you previously hid the
  4932. frontmost window with HideWindow, HideWindow will have brought the
  4933. window behind it to the front; so if you then do a ShowWindow of the
  4934. window you hid, it will no longer be frontmost (see Figure 6 above).
  4935. If the Window is already visible, ShowWindow has no effect.
  4936.  
  4937. (note)
  4938.     Although it's inadvisable, you can create a situation 
  4939.     where the frontmost window is invisible. If you do a
  4940.     ShowWindow of such a window, it will highlight the window
  4941.     if it's not already highlighted and will generate an 
  4942.     activate event to force this window from inactive to
  4943.     active.
  4944. \ ShowHide
  4945. 5
  4946. PROCEDURE ShowHide (theWindow: WindowPtr; showFlag: (BOOLEAN);
  4947.  
  4948.     If showFlag is FALSE, ShowHide makes theWindow invisible if it's not
  4949. already invisible and has no effect if it is already invisible. If
  4950. showFlag is TRUE, ShowHide makes the Window visible if it's not already
  4951. visible and has no effect if it is already visible. Unlike HideWindow
  4952. and ShowWindow, ShowHide never changes the highlighting or front-to-
  4953. back ordering of windows or generates activates events.
  4954.  
  4955. (warning)
  4956.     Use this procedure carefully, and only in special
  4957.     circumstances where you need more control than allowed by
  4958.     HideWindow and ShowWindow.
  4959. \ HiliteWindow
  4960. 5
  4961. PROCEDURE HiliteWindow (theWindow: WindowPtr; fHilite: BOOLEAN);
  4962.  
  4963.     If fHilite isTRUE, this procedure highlights theWindow if it's not
  4964. already highlighted and has no effect if it is highlighted. If fHilite
  4965. is FALSE, HiliteWindow unhighlights theWindow if it is highlighted and
  4966. has no effect if it's not highlighted. The exact way a window is 
  4967. highlighted depdnds on its window definition function.
  4968.  
  4969.     Normally you won't have to call this procedure, since you should
  4970. call SelectWindow to make a window active, and SelectWindow takes care
  4971. of the necessary highlighting changes. Highlighting a window that isn't 
  4972. the active window is contrary to the Macintosh User Interface
  4973. Guidelines.
  4974. \ BringToFront
  4975. 5
  4976. PROCEDURE BringToFront (theWindow: WindowPtr);
  4977.  
  4978.     BringToFront brings theWindow to the front of all other windows and
  4979. redraws the window as necessary. Normally you won't have to call this 
  4980. procedure, since you should call SelectWindow to make a window active,
  4981. and SelectWindow takes care of bringing the window to the front. If
  4982. you do call BringToFront, however, remember to call HiliteWindow to
  4983. make the necessary highlighting changes.
  4984. \ SendBehind
  4985. 5
  4986. PROCEDURE SendBehind (theWindow: WindowPtr; behindWindow: WindowPtr);
  4987.  
  4988.     SendBehind sends theWindow behind behindWindow, redrawing any
  4989. exposed windows. If behindWindow is NIL, it sends theWindow behind all
  4990. other windows. If theWindow is the active window, it unhighlights the
  4991. Window, highlights the new active window, and generates the appropriate
  4992. activate events.
  4993.  
  4994. (warning)
  4995.     Do not use SendBehind to deactivate a previously active
  4996.     window. Calling SelectWindow to make a window active
  4997.     takes care of deactivating the previously active window.
  4998.  
  4999. (note)
  5000.     If you're moving theWindow closer to the front (that is,
  5001.     if it's initially even farther behind behind(Window), you
  5002.     must make the following calls after calling SendBehind:
  5003.  
  5004.         wPeek := POINTER(theWindow);
  5005.         PaintOne(wPeek, wPeek^.strucRgn);
  5006.         CalcVis(wPeek)
  5007.  
  5008.     PaintOne and CalcVis are described below under "Low'Level
  5009.     Routines".
  5010. \ FrontWindow
  5011. 5
  5012. FUNCTION FrontWindow : WindowPtr;
  5013.  
  5014.     FrontWindow returns a pointer to the first visible window in the
  5015. window list (that is, the active window). If there are no visible
  5016. windows, it returns NIL.
  5017. \ DrawGrowIcon
  5018. 5
  5019. PROCEDURE DrawGrowIcon (theWindow: WindowPtr).
  5020.  
  5021.     Call DrawGrowIcon in responce to an update or activate event
  5022. involving a window that contains a size box in its content region. If
  5023. theWindow is active (highlighted), DrawGrowIcon draws the size box;
  5024. otherwise, it draws whatever is appropriate to show that thewindow
  5025. temporily cannot be sized. The exact appearance and location of what's
  5026. drawn depend on the window definition function. For an active document
  5027. window, DrawGrowIcon draws the size box icon in the bottom right corner
  5028. of the portRect of the window's grafPort, along with the lines
  5029. delimiting the size box and scroll bar areas (15 pixels in from the
  5030. right edge and bottom of the portRect). It doesn't erase the scroll
  5031. bar areas, so if the window doesn't contain scroll bars you should 
  5032. erase those areas yourself after the window's size changes. For an 
  5033. inactive document window, DrawGrowIcon draws only the delimiting lines
  5034. (again, without erasing anything).
  5035. \ FindWindow
  5036. 5
  5037. FUNCTION FindWindow (thePt: Point; VAR whichWindow: WindowPtr) :
  5038.     INTEGER;
  5039.  
  5040.     When a mouse-down event occurs, the application should call
  5041. FindWindow with thePt equal to the point where the mouse button was
  5042. pressed (in global coordinates, as stored in the where field of the
  5043. event record). FindWindow tells which part of which window, if any, the
  5044. mouse button was pressed in. If it was pressed in a window, the
  5045. whichWindow parameter is set to the window pointer; otherwise, it's set
  5046. to NIL. The integer returned by FindWindow is one of the following
  5047. predefined constants:
  5048.  
  5049. CONST inDesk      = Ø;  {none of the following}
  5050.       InMenuBar   = 1;  {in menu bar}
  5051.       inSysWindow = 2;  {in system window}
  5052.       inContent   = 3;  {in content region (except grow, if active)}
  5053.       inDrag      = 4;  {in drag region}
  5054.       inGrow      = 5;  {in grow region (active window only)}
  5055.       inGoAway    = 6;  {in go-away region (active window only)}
  5056.       inZoomin    = 7;
  5057.       inZoomOut   = 8;
  5058.  
  5059.     InDesk usually means that the mouse button was pressed on the
  5060. desktop, outside the menu bar or any windows; however, it may also mean
  5061. that the mouse button was pressed inside a window frame but not in the
  5062. drag region or go-away region of the window. Usually one of the last
  5063. four values is returned for windows created by the application.
  5064.  
  5065.     If the window is a documentProc type of window that doesn't contain
  5066. a size box, the application should treat  inGrow the same as inContent;
  5067. if it's a noGrowDocProc type of window, FindWindow will never return 
  5068. inGrow for that window. If the window is a documentProc, noGrowDocProc,
  5069. or rDocProc type of window with no close box, FindWindow will never
  5070. return inGoAway for that window.
  5071. \ TrackGoAway
  5072. 5
  5073. FUNCTION TrackGoAway (theWindow: WindowPtr; thePt: Point) : BOOLEAN;
  5074.  
  5075.     When there's a mouse-down event in the go-away region of theWindow,
  5076. the application should call TrackGoAway with thePt equal to the point
  5077. where the mouse button was pressed (in global coordinates, as stored in
  5078. the where field of the event record). TrackGoAway keeps control until
  5079. the mouse button is released, highlighting the go-away region as long as
  5080. the mouse position remains inside it, and unhighlighting it when the
  5081. mouse moves outside it. The exact way a window's go-away region is 
  5082. highlighted depends on its window definition function; the highlighting
  5083. of a document window's close box is illustrated in Figure 7. When the 
  5084. mouse  button is released, TrackGoAway unhighlights the go-away region
  5085. and returns TRUE if the mouse is inside the go-away region or FALSE if
  5086. it's outside the region (in which case the application should do
  5087. nothing).
  5088. \ MoveWindow
  5089. 5
  5090. PROCEDURE MoveWindow (theWindow: WindowPtr; hGlobal,vGlobal: INTEGER;
  5091.     front: BOOLEAN);
  5092.  
  5093.     MoveWindow moves theWindow to another part of the screen, without
  5094. affecting its size or plane.  The top left corner of the portRect of
  5095. the window's grafPort is moved to the screen point indicated by the 
  5096. global coordinates hGlobal and vGlobal. The local coordinates of the
  5097. top left corner remain the same; MoveWindow saves those coordinates
  5098. before moving the window and calls the QuickDraw procedure SetOrigin to
  5099. restore them before returning. If the front parameter is TRUE and
  5100. theWindow isn't the active window, MoveWindow makes it the active 
  5101. window by calling SelectWindow(theWindow).
  5102. \ DragWindow
  5103. 5
  5104. PROCEDURE DragWindow (theWindow: WindowPtr; startPt: Point; boundsRect:
  5105.     Rect);
  5106.  
  5107.     When there's a mouse-down event in the drag region of theWinow, the 
  5108. application should call DragWindow with StartPt equal to the point
  5109. where the mouse button was pressed (in global coordinates, as stored in
  5110. the where field of the event record). DragWindow pulls a gray outline
  5111. of theWindow around, following the movements of the mouse until the
  5112. button is released. When the mouse button is released, DragWindow
  5113. calls MoveWindow to move theWindow to the location to which it was
  5114. dragged. If theWindow is not the active window and the Command key was
  5115. not being held down, DragWindow makes it the active window (by passing
  5116. TRUE for the front parameter when calling MoveWindow).
  5117.  
  5118.     BoundsRect is also given in global coordinates. If the mouse button
  5119. is released when the mouse position is outside the limits of boundsRect,
  5120. DragWindow returns without moving theWindow or making it the active
  5121. window. For a document window, boundsRect typically will be four
  5122. pixels in from the menu bar and from the other edges of the screen, to
  5123. ensure that there won't be less than a four-pixel-square area of the 
  5124. title bar visible on the screen.
  5125. \ GrowWindow
  5126. 5
  5127. FUNCTION GrowWindow (theWindow: WindowPtr; startPt: Point; sizeRect:
  5128.     Rect) : LongInt;
  5129.  
  5130.     When there's a mouse-down event in the grow region of theWindow, the 
  5131. application should call GrowWindow with startPt equal to the point
  5132. where the mouse button was pressed (in global ccoordinates, as stored in
  5133. the where field of the event record). GrowWindow pulls a GROW IMAGE of
  5134. the window around, following the movements of the mouse until the
  5135. button is released. The grow image for a document window is a gray
  5136. outline of the entire window and also the lines delimiting the title
  5137. bar, size box, and scroll bar areas; Figure 8 illustrates this for a
  5138. document window containing a size box and scroll bars, but the grow
  5139. image would be the same even if the window contained no size box, one
  5140. scroll bar, or no scroll bars. In general, the grow image is defined
  5141. in the window definition function and is whatever is appropriate to
  5142. show that the window's size will change. 
  5143.  
  5144.     The application should subsequently call SizeWindow (see below) to
  5145. change the portRect of the window's grafPort to the new one outlined by 
  5146. the grow image. The sizeRect parameter specifies limits, in pixels, on
  5147. the vertical and horizontal measurements of what will be the new
  5148. portRect. SizeRect.top is the minimum vertical measurement,
  5149. sizeRect.left is the minimum horizontal measurement, sizeRect.bottom is
  5150. the maximum vertical measurement, and sizeRect.right is the maximum
  5151. horizontal measurement.
  5152.  
  5153.     GrowWindow returns the actual size for the new portRect as outlined
  5154. by the grow image when the mouse button is released. The high-order
  5155. word of the LongInt is the vertical measurement in pixels and the
  5156. low-order word is the horizontal measurement. A return value of Ø
  5157. indicates that the size is the same as that of the current portRect.
  5158.  
  5159. (note)
  5160.     The Toolbox Utility function HiWord takes a long integer
  5161.     as a parameter and returns an integer equal to its high-
  5162.     order word; the function LoWord returns the low-order
  5163.     word.
  5164. \ SizeWindow
  5165. 5
  5166. PROCEDURE SizeWindow (theWindow: WindowPtr; w,h: INTEGER; fUpdate:
  5167.     BOOLEAN);
  5168.  
  5169.     SizeWindow enlarges or shrinks the portRect of the Window's grafPort
  5170. to the width and height specified by w and h, or does nothing if w and h
  5171. are Ø. The window's position on the screen does not change. The new 
  5172. window frame is drawn; if the width of a document window changes, the
  5173. title is again centered in the title bar, or is truncated at its end if
  5174. it no longer fits. If fUpdate is TRUE, SizeWindow accumulates any
  5175. newly created area of the content region into the update region (see
  5176. figure 9);  normally this is what you'll want. If you pass FALSE for 
  5177. fUpdate, you're responsible for the update region maintenance yourself.
  5178. For more information, see InvalRect and ValidRect below.
  5179.  
  5180. (note)
  5181.     You should change the window's size only when the user 
  5182.     has done something specific to make it change.
  5183. \ InvalRect
  5184. 5
  5185. PROCEDURE InvalRect (badRect: Rect);
  5186.  
  5187.     InvalRect accumulates the given rectangle into the update region of
  5188. the window whose grafPort is the current port. This tells the Window
  5189. Manager that the rectangle has changed and must be updated. The
  5190. rectangle lies within the window's content region and is given in the 
  5191. local coordinates.
  5192.  
  5193.     For example, this procedure is useful when you're calling SizeWindow 
  5194. (described above) for a document window that contains a size box or
  5195. scroll bars. Suppose yuou're going to call SizeWindow with 
  5196. fUpdate=TRUE. If the window is enlarged as shown in Figure 8 above,
  5197. you'll want not only the newly created part of the content region to be 
  5198. updated, but also the two rectangular areas containing the (former)
  5199. size box and scroll bars; before calling SizeWindow, you can call
  5200. InvalRect twice to accumulate those areas into the update region. In
  5201. case the window is made smaller, you'll want the new size box and 
  5202. scroll bar areas to be updated, and so can similarly call InvalRect for
  5203. those areas after calling SizeWindow. See Figure 1Ø for an
  5204. iillustration of this type of update region maintenance.
  5205.  
  5206.     As another example, suppose your application scrolls up text in a
  5207. document window and wants to show new text added at the bottom of the
  5208. window. You can cause the added text to be redrawn by accumulating
  5209. that area into the update region with InvalRect.
  5210. \ InvalRgn
  5211. 5
  5212. PROCEDURE InvalRgn (badRgn: RgnHandle);
  5213.  
  5214.     InvalRgn is the same as InvalRect (above) but for a region that has
  5215. changed rather than a rectangle.
  5216. \ ValidRect
  5217. 5
  5218. PROCEDURE ValidRect (goodRect: Rect);
  5219.  
  5220.     ValidRect removes goodRect from the update region of the window
  5221. whose grafPort is the current port. This tells the Window Manager that
  5222. the application has already drawn the rectangle and to cancel any
  5223. updates accumulated for that area. The rectangle lies within the
  5224. window's content region and is given in local coordinates. Using
  5225. ValidRect results in better performance and less redundant redrawing in
  5226. the window.
  5227.  
  5228.     For example, suppose you've called SizeWindow (described above) with 
  5229. fUpdate=TRUE for a document window that contains a size box or scroll
  5230. bars. Depending on the dimensions of the newly sized window, the new
  5231. size box and scroll bar areas may or may not have been accumulated into
  5232. the window's update region. After calling SizeWindow, you can redraw
  5233. the size box or scroll bars immediately and then call ValidRect for the
  5234. areas they occupy in case they were in fact accumulated into the update
  5235. region; this will avoid redundant drawing.
  5236. \ ValidRgn
  5237. 5
  5238. PROCEDURE ValidRgn (goodRgn: RgnHandle);
  5239.  
  5240.     ValidRgn is the same as ValidRect (above) but for a region that has
  5241. been drawn rather than a rectangle.
  5242. \ BeginUpdate
  5243. 5
  5244. PROCEDURE BeginUpdate (theWindow: WindowPtr);
  5245.  
  5246.     Call BeginUpdate when an update event occurs for theWindow.
  5247. BeginUpdate replaces the visRgn of the window's grafPort with the 
  5248. intersection of the visRgn and the update region and then sets the
  5249. window's update region to the empty region. You would then usually
  5250. draw the entire content region, though it suffices to draw only the
  5251. visRgn; in either case, only the parts of the window that require
  5252. updating will actually be drwn on the screen. Every call to
  5253. BeginUpdate must be balanced by a call to EndUpdate. (See below, and
  5254. see "How a Window is Drawn".)
  5255. \ EndUpdate
  5256. 5
  5257. PROCEDURE EndUpdate (theWindow: WindowPtr);
  5258.  
  5259.     Call EndUpdate to restore the normal visRgn of theWindow's grafPort, 
  5260. which was changed by BeginUpdate as described above.
  5261. \ SetWRefCon
  5262. 5
  5263. PROCEDURESetWRefCon (theWindow: WindowPtr; data: LongInt);
  5264.  
  5265.     SetWRefCon sets theWindow's reference value to the given data.
  5266. \ GetWRefCon
  5267. 5
  5268. FUNCTION GetWRefCon (theWindow: WindowPtr) : LongInt;
  5269.  
  5270.     GetWRefCon returns theWindow's current reference value. 
  5271. \ SetWindowPic
  5272. 5
  5273. PROCEDURE SetWindowPic (theWindow: WindowPtr; pic: PicHandle);
  5274.  
  5275.     SetWindowPic stores the given picture handle in the window record
  5276. for theWindow, so that when theWindow's contents are to be drawn, the 
  5277. Window Manager will draw this picture rather than generate an update
  5278. event.
  5279. \ GetWindowPic
  5280. 5
  5281. FUNCTION GetWindowPic (theWindow: WindowPtr) : PicHandle;
  5282.  
  5283.     GetWindowPic returns the handle to the picture that draws
  5284. theWindow's contents, previously stored with SetWindowPic (above).
  5285. \ PinRect
  5286. 5
  5287. FUNCTION PinRect (theRect: Rect; thePt: Point) : LongInt;
  5288.  
  5289.     PinRect "pins" thePt inside theRect: The high-order word of the
  5290. function result is the vertical coordinate of thePt or, if thePt lies
  5291. above or below theRect, the vertical coordinate of the top or bottom of
  5292. theRect, respectively. The low-order word of the function result is
  5293. the horizontal coordinate of thePt or, if thePt lies to the left or
  5294. right of theRect, the horizontal coordinate of the left or right edge
  5295. of theRect.
  5296. \ DragGrayRgn
  5297. 5
  5298. FUNCTION DragGrayRgn (theRgn: RgnHandle; startPt: Point;
  5299.     limitRect,slopRect: Rect; axis: INTEGER; actionProc:
  5300.     ProcPtr : LongInt;
  5301.  
  5302.     Called when the mouse button is down inside theRgn, DragGrayRgn
  5303. pulls a gray outline of the region around, following the movements of
  5304. the mouse until the button is released. DragWindow calls this function
  5305. before actually moving the window, and the Control Manager routine
  5306. DragControl similarly calls it for controls. You can call it yourself
  5307. to pull around the outline of any region, and then use the information
  5308. it returns to determine where to move the region.
  5309.  
  5310.     The startPt parameter is assumed to be the point where the mouse
  5311. button was orignally pressed, in the local coordinates of the current
  5312. LimitRect and slopRect are also in the local coordinates of the current
  5313. grafPort. To explain these parameters, the concept of "offset point"
  5314. must be introduced: this is the point whose vertical and horizontal
  5315. offsets from the top left corner of the region's enclosing rectangle 
  5316. are the same as those of startPt. Initially the offset point is the
  5317. same as the mouse position, but they may differ, depending on where the
  5318. user moves the mouse. DragGrayRgn will never move the offset point
  5319. outside limitRect; this limits the travel of the region's outline (but
  5320. not the movements of the mouse). SlopRect, which should completely
  5321. enclose limitRect, allows the user some "slop" in moving the mouse.
  5322. DragGrayRgn's behavior while tracking the mouse depends on the position 
  5323. of the mouse with respect to these two rectangles
  5324.  
  5325.    - when the mouse is inside limitRect, the region's outline follows
  5326.      it normally. If the mouse button is released there, the region
  5327.      should be moved to the mouse position.
  5328.  
  5329.    - When the mouse is outside limitRect but inside slopRect,
  5330.      DragGrayRgn "pins" the offset point to the edge of limitRect. If
  5331.      the mouse button is released there, the region should be moved to
  5332.      this pinned location.
  5333.  
  5334.    - When the mouse is outside slopRect, the outline disappears from
  5335.      screen, but DragGrayRgn continues to follow the mouse; if it
  5336.      moves back into slopRect, the outline reappears. If the mouse
  5337.      button is released outside slopRect, the region should not be
  5338.      moved from its original position.
  5339.  
  5340.     Figure 11 illustrates what happens when the mouse is moved outside
  5341. limitRect but inside slopRect, for a rectangular region. The offset
  5342. point is pinned as the mouse position moves on.
  5343.  
  5344.     If the mouse button is released outside slopRect, DragGrayRgn
  5345. returns -32768 ($8ØØØ); otherwise, the high-order word of the value
  5346. returned contains the vertical coordinate of the ending mouse point
  5347. minus that of startPt and the low-order word contains the difference
  5348. between the horizontal coordinates.
  5349.  
  5350.     The axis parameter allows you to constrain the outline's motion to
  5351. only one axis. It has one of the following values:
  5352.  
  5353.     CONST noConstraint = Ø;     {no constraint}
  5354.           hAxis Only   = 1;     {horizontal axis only}
  5355.           vAxis Only   = 2;     {vertical axis only}
  5356.  
  5357.     If noaxis constraint is in effect, the outline will follow the
  5358. mouse's movements along the specified axis only, ignoring motion along
  5359. the other axis. With or without an axis constraint, the mouse must
  5360. still be inside the slop rectangle for the outline to appear at all.
  5361.  
  5362.     The actionProc parameter is a pointer to a procedure that defines
  5363. some action to be performed repeatedly for as long as the user holds
  5364. down the mouse button; the procedure should have no parameters. If
  5365. actionProc is NIL, DragGrayRgn simply retains control until the mouse
  5366. button is released, performing no action while the mouse button is
  5367. down.
  5368. \ CheckUpdate
  5369. 5
  5370. FUNCTION CheckUpdate (VAR the Event: EventRecord) : BOOLEAN;
  5371.  
  5372.     CheckUpdate is called by the Toolbox Event Manager. From the front
  5373. to the back in the window list, it looks for a visible window that needs
  5374. updating (that is, whose update region is not empty). If it finds one
  5375. whose window record contains a picture handle, it draws the picture
  5376. (doing all the necessary region manipulation) and looks for the next
  5377. visible window that needs updating. If it ever finds one whose window
  5378. record doesn't contain a picture handle, it stores an update event for 
  5379. that window in theEvent and returns TRUE. If it never finds such a
  5380. window, it returns FALSE.
  5381. \ ClipAbove
  5382. 5
  5383. PROCEDURE ClipAbove (window: WindowPeek);
  5384.  
  5385.     ClipAbove sets the clipRgn of the Window Manager port to be the
  5386. desktop (global variable grayRgn) intersected with the current clipRgn,
  5387. minus the structure regions of all the windows above the given window.
  5388. \ SaveOld
  5389. 5
  5390. PROCEDURE SaveOld (window: WindowPeek);
  5391.  
  5392.     SaveOld saves the given window's current structure region and
  5393. content region for the DrawNew operation (see below). It must be
  5394. balanced by a subsequent call to DrawNew.
  5395. \ DrawNew
  5396. 5
  5397. PROCEDURE DrawNew (window: WindowPeek; update: BOOLEAN);
  5398.  
  5399.     If the update parameter is TRUE, DrawNew updates the area.
  5400.  
  5401.     (oldStruct XOR newStruct) UNION oldContent XOR newContent)
  5402.  
  5403.     where oldStruct and oldContent are the structure and content regions
  5404. saved by the SaveOld procedures, and newStruct and newContent are the
  5405. current structure and content regions. It paints the area white and
  5406. adds it to the window's update region. If update is FALSE, it only
  5407. paints the area white.
  5408.  
  5409. (warning)
  5410.     SaveOld and DrawNew are not nestable.
  5411. \ PaintOne
  5412. 5
  5413. PROCEDURE PaintOne (window: WindowPeek; clobberedRgn: RgnHandle);
  5414.  
  5415.     PaintOne "paints" the given window, clipped to clobberedRgn and all
  5416. windows above it: it draws the window frame and, if some content is
  5417. exposed, paints the exposed area white and adds it to the window's 
  5418. update region. If the window parameter is NIL, the window is the
  5419. desktop and so is painted gray.
  5420. \ PaintBehind
  5421. 5
  5422. PROCEDURE PaintBehind (startWindow: WindowPeek; clobberedRgn:
  5423.     RgnHandle);
  5424.  
  5425.     PaintBehind calls PaintOne (above for startWindow and all the
  5426. windows behind startWindow, clipped to clobberedRgn.
  5427. \ CalcVis
  5428. 5
  5429. PROCEDURE CalcVis (window: WindowPeek);
  5430.  
  5431.     CalVis calculates the visRgn of the given window by starting with
  5432. its content region and subtracting the structure region of each window
  5433. in front of it.
  5434. \ CalcVisBehind
  5435. 5
  5436. PROCEDURE CalcVisBehind (startWindow: WindowPeek; clobberedRgn:
  5437.     RegHandle;
  5438.  
  5439.     CalcVisBehind calculates the visRgns of start Window and all windows
  5440. behind startWindow that intersect with clobberedRgn. It's called after 
  5441. PaintBehind (see  above).
  5442. \ TrackBox
  5443. 5
  5444. FUNCTION TrackBox (theWindow: WindowPtr; thePt: Point;
  5445.                     partCode: INTEGER) : BOOLEAN;
  5446.  
  5447.     When there’s a mouse-down event in the zoom-window box of theWindow,
  5448. the application should call TrackBox with thePt equal to the point
  5449. where the mouse button was pressed (in global coordinates, as stored
  5450. in the where field of the event record). The partCode parameter
  5451. contains the constant (either inZoomIn or inZoomOut) returned by
  5452. FindWindow. TrackBox keeps control until the mouse button
  5453. is released; it highlights the zoom-window box in the same way as
  5454. a window’s close box is highlighted. When the mouse button is released,
  5455. TrackBox unhighlights the zoom-window box and returns TRUE if
  5456. the mouse is inside the zoom-window box or FALSE if it’s outside
  5457. the box (in which case the application should do nothing).
  5458. \ ZoomWindow
  5459. 5
  5460. PROCEDURE ZoomWindow (theWindow: WindowPtr;
  5461.                         partCode: INTEGER; front: BOOLEAN);
  5462.  
  5463.     Call ZoomWindow after a call to TrackBox that returns TRUE.
  5464. The partCode parameter contains the constant (either inZoomIn or
  5465. inZoomOut) returned by FindWindow. The window will be zoomed either
  5466. out or in, depending on the state of the window specified by partCode.
  5467. If the window is already in the state specified by partCode, ZoomWindow
  5468. does nothing. If the front parameter is TRUE, the window will be
  5469. brought to the front; otherwise, the window is left where it is.
  5470. (This means a window can be zoomed without necessarily becoming
  5471. the active window.)
  5472.  
  5473.     For best results, call the QuickDraw procedure EraseRect with the
  5474. portRect field of theWindow’s grafPort before calling ZoomWindow.
  5475.  
  5476. Warning:  Using the QuickDraw procedure SetPort, set thePort to the
  5477.           window’s port before calling ZoomWindow.
  5478.  
  5479. Note:     ZoomWindow is in no way tied to the TrackBox function and
  5480.           could just as easily be called in response to a selection
  5481.           from a menu.
  5482. \ NewControl
  5483. 6
  5484. FUNCTION NewControl (theWindow: WindowPtr; boundsRect: Rect; title:
  5485.                     Str255; visible: BOOLEAN; value: INTEGER;
  5486.                     min,max: INTEGER; procID: INTEGER; refCon: LongInt)
  5487.                     : ControlHandle;
  5488.  
  5489.  
  5490.     NewControl creates a control, adds it to the beginning of
  5491. theWindow's control list, and returns a handle to the new control. The
  5492. values passed as parameters are stored in the corresponding fields of
  5493. the control record, as described below. The field that determines
  5494. highlighting is set to Ø (no highlighting) and the pointer to the
  5495. default action procedure is set to NIL (none).
  5496.  
  5497. (note)
  5498.     The control definition function may do additional
  5499.     initialization, including changing any of the fields of
  5500.     the control record. The only standard control for which
  5501.     additional initialization is done is the scroll bar; its
  5502.     control definition function allocates space for a region
  5503.     to hold the thumb and stores the region handle in the
  5504.     contrlData field of the control record.
  5505.  
  5506.     TheWindow is the window the new control will belong to. All
  5507. coordinates pertaining to the control will be interpreted in this
  5508. window's local coordinate system.
  5509.  
  5510.     BoundsRect, given in theWindow's local coordinates, is the rectangle 
  5511. that encloses the control and thus determines its size and location.
  5512. Note the following about the enclosing rectangle for the standard
  5513. controls:
  5514.  
  5515.       - Simple buttons are drawn to fit the rectangle exactly. (The
  5516.         control definition function calls the QuickDraw procedure
  5517.     FrameRoundRect.)  To allow for the tallest characters in the
  5518.     system font, there should be at least a 2Ø-point difference
  5519.     between the top and bottom coordinates of the rectangle.
  5520.  
  5521.       - For check boxes and radio buttons, there should be at least a
  5522.     16-point difference between the top and bottom coordinates.
  5523.  
  5524.       - By convention, scroll bars are 16 pixels wide, so there should be
  5525.     a 16-point difference between the left and right (or top and
  5526.     bottom) coordinates. If there isn't, the scroll bar will be 
  5527.     scaled to fit the rectangle.
  5528.  
  5529.     Title is the control's title, if any (if none, you can just pass the 
  5530. empty string as the title). Be sure the title will fit in the
  5531. control's enclosing rectangle; if it won't, it will be truncated on the
  5532. right for check boxes and radio buttons, or centered and truncated on
  5533. both ends for simple buttons.
  5534.  
  5535.     If the visible parameter is TRUE, NewControl draws the control.
  5536.  
  5537. (note)
  5538.     It does NOT use the standard window updating mechanism,
  5539.     but instead draws the control immediately in the window.
  5540.  
  5541.     The min and max parameters define the control's range of possible 
  5542. settings; the value parameter gives the initial setting. For controls
  5543. that don't retain a setting, such as buttons, the values you supply for 
  5544. these parameters will be stored in the control record but will never be
  5545. used. So it doesn't matter what values you give for those controls--Ø
  5546. for all three parameters will do. For controls that just retain an
  5547. on-or-off setting, such as check boxes or radio buttons, min should be
  5548. Ø (meaning the control is off) and max should be 1 (meaning it's on).
  5549. For dials, you can specify whatever values are appropriate for min,
  5550. max, and value.
  5551.  
  5552.     ProcID is the control definition ID, which leads to the control
  5553. definition function for this type of control. The control definition
  5554. IDs for the standard control types are listed above under "Controls and 
  5555. Resources". Control definition IDs for custom control types are 
  5556. discussed later under "Defining Your Own Controls".
  5557.  
  5558.     RefCon is the control's reference value, set and used only by your 
  5559. application.
  5560. \ GetNewControl
  5561. 6
  5562. FUNCTION GetNewControl (controlID: INTEGER; theWindow: WindowPtr)
  5563.                         : ControlHandle;
  5564.  
  5565.     GetNewControl creates a control from a control template stored in a
  5566. resource file, adds it to the beginning of theWindow's control list, 
  5567. and returns a handle to the new control. ControlID is the resource ID
  5568. of the template. GetNewControl works exactly the same as NewControl
  5569. (above), except thatt it gets the initial values for the new control's
  5570. fields from the specified control template instead of accepting them as
  5571. parameters.
  5572. \ DisposeControl
  5573. 6
  5574. PROCEDURE DisposeControl (theControl: ControlHandle);
  5575.  
  5576.     DisposeControl removes theControl from the screen, deletes it from
  5577. its window's control list, and releases the memory occupied by the
  5578. control record and all data structures associated with the control.
  5579. \ KillControls
  5580. 6
  5581. PROCEDURE KillControls (theWindow: WindowPtr);
  5582.  
  5583.     KillControls disposes of all controls associated with theWindow by
  5584. calling DisposeControl (above) for each.
  5585. \ SetCTitle
  5586. 6
  5587. PROCEDURE SetCTitle (theControl: ControlHandle; title: Str255);
  5588.  
  5589.     SetCTitle sets theControl's title to the given string and redraws
  5590. the control.
  5591. \ GetCTitle
  5592. 6
  5593. PROCEDURE GetCTitle (theControl: ControlHandle; VAR title: Str255);
  5594.  
  5595.     GetCTitle returns theControl's title as the value of the title 
  5596. parameter.
  5597. \ HideControl
  5598. 6
  5599. PROCEDURE HideControl (theControl: ControlHandle);
  5600.  
  5601.     HideControl makes theControl invisible. It fills the region the
  5602. control occupies within its window with the background pattern of the
  5603. window's grafPort. It also adds the control's enclosing rectangle to
  5604. the window's update region, so that anything else that was previously 
  5605. obscured by the control will reappear on the screen. If the control is
  5606. already invisible, HideControl has no effect.
  5607. \ ShowControl
  5608. 6
  5609. PROCEDURE ShowControl (theControl: ControlHandle);
  5610.  
  5611.     ShowControl makes theControl visible. The control is drawn in its
  5612. window but may be completely or partially obscured by overlapping
  5613. windows or other objects. If the control is already visible,
  5614. ShowControl has no effect.
  5615. \ DrawControls
  5616. 6
  5617. PROCEDURE DrawControls (theWindow: WindowPtr);
  5618.  
  5619.     DrawControls draws all controls currently visible in theWindow. The
  5620. controls are drawn in reverse order of creation; thus in case of
  5621. overlap the earliest-created controls appear frontmost in the window.
  5622.  
  5623. (note)
  5624.     WindowManager routines such as SelectWindow, ShowWindow,
  5625.     and BringToFront do not automatically call DrawControls
  5626.     to display the window's controls. They just add the 
  5627.     appropriate regions to the window's update region, 
  5628.     generating an update event. Your program should always
  5629.     call DrawControls explicitly upon receiving an update
  5630.     event for a window that contains controls.
  5631. \ HiliteControl
  5632. 6
  5633. PROCEDURE HiliteControl (theControl: ControlHandle; hiliteState:
  5634.                         INTEGER);
  5635.  
  5636.     HiliteControl changes the way theControl is highlighted. HiliteState
  5637. is an integer between Ø and 255;
  5638.  
  5639.        - A value of Ø means no highlighting.
  5640.  
  5641.        - A value between 1 and 253 is interpreted as a part code
  5642.          designating the part of the control to be highlighted.
  5643.  
  5644.        - A value of 254 or 255 means that the control is to be made
  5645.          inactive and highlighted accordingly. Usually you'll want to
  5646.          use 254, because it enables you to detect when the mouse button
  5647.          was pressed in the inactive control as opposed to not in any
  5648.          control;
  5649.          for more information, see FindControl under "Mouse Location"
  5650.          below.
  5651.  
  5652.     Hilite Control calls the control definition function to redraw the
  5653. control with its new highlighting.
  5654. \ TestControl
  5655. 6
  5656. FUNCTION TestControl (theControl: ControlHandle; thePoint: Point)
  5657.                         :  INTEGER;
  5658.  
  5659.     If theControl is visible and active, TestControl tests which part of
  5660. the control contains thePoint (in the local coordinates of the
  5661. control's window); it returns the corresponding part code, or Ø if the 
  5662. point is outside the control. If the control is visible and inactive
  5663. with 254 highlighting, TestControl returns 254. If the control is
  5664. invisible, or inactive with 255 highlighting, TestControl returns Ø.
  5665. \ FindControl
  5666. 6
  5667. FUNCTION FindControl (thePoint: Point; theWindow: WindowPtr; VAR
  5668.                         whichControl: ControlHandle) : INTEGER;
  5669.  
  5670.     When the Window Manager function FindWindow reports that the mouse
  5671. button was pressed in the content region of a window, and the window
  5672. contains controls, the application should call FindControl with
  5673. theWindow equal to the window pointer and thePoint equal to the point
  5674. where the mouse button was pressed (in the window's local coordinates).
  5675. FindControl tells which of the window's controls, if any, the mouse 
  5676. button was pressed in:
  5677.  
  5678.       - If it was pressed in a visible, active control, FindControl sets
  5679.         the whichControl parameter to the control handle and returns a
  5680.         part code identifying the part of the control that it was
  5681.         pressed in.
  5682.  
  5683.       - If it was pressed in a visible, inactive control with 254
  5684.         highlighting, FindControl sets whichControl to the control
  5685.         handle and returns 254 as its result.
  5686.  
  5687.       - If it was pressed in an invisible control, an inactive control
  5688.         with 255 highlighting, or not in any control, FindControl sets
  5689.         whichControl to NIL and returns Ø as its result.
  5690.  
  5691. (warning)
  5692.     Notice that FindControl expects the mouse point in the
  5693.     window's local coordinates, whereas FindWindow expects it 
  5694.     in global coordinates. Always be sure to convert the
  5695.     point to local coordinates with the QuickDraw procedure
  5696.     GlobalToLocal before calling FindControl.
  5697.  
  5698. (note)
  5699.     FindControl also returns NIL for whichControl and Ø as
  5700.     its result if the window is invisible or doesn't contain 
  5701.     the given point. In these cases, however, FindWindow
  5702.     wouldn't have returned this window in the first place, so 
  5703.     the situation should never arise.
  5704. \ TrackControl
  5705. 6
  5706. FUNCTION TrackControl (theControl: ControlHandle; startPt: Point;
  5707.     actionProc: ProcPtr) : INTEGER;
  5708.  
  5709.     When the mouse button is pressed in a visible, active control, the
  5710. application should call TrackControl with theControl equal to the
  5711. control handle and startPt equal to the point where the mouse button
  5712. was pressed (in the local coordinates of the control's window).
  5713. TrackControl follows the movements of the mouse and responds in
  5714. whatever way is appropriate until the mouse button is released; the
  5715. exact response depends on the type of control and the part of the
  5716. control in which the mouse button was pressed. If highlighting is
  5717. appropriate, TrackControl does the highlighting, and undoes it before
  5718. returning. When the mouse button is released, TrackControl returns
  5719. with the part code if the mouse is in the same part of the control that
  5720. it was originally in, or with Ø if not (in which case the application
  5721. should do nothing.
  5722.  
  5723.     If the mouse button was pressed in an indicator, TrackControl drags
  5724. a gray outline of it to follow the mouse (by calling the Window Manager
  5725. utility function DragGrayRgn). When the mouse button is released,
  5726. TrackControl calls the control definition function to reposition the
  5727. control's indicator. The control definition function for scroll bars 
  5728. responds by redrawing the thumb, calculating  the control's current 
  5729. setting based on the new relative position of the thumb, and storing
  5730. the current setting in the control record; for example, if the minimum
  5731. and maximum settings are  Ø and 1Ø, and the thumb is in the middle of
  5732. the scroll bar, 5 is stored as the current setting. The application
  5733. must then scroll to the corresponding relative position in the
  5734. document.
  5735.  
  5736.     TrackControl may take additional actions beyond highlighting the
  5737. control or dragging the indicator, depending on the value passed in the
  5738. actionProc parameter, as described below. Here you'll learn what to 
  5739. pass for the standard control types; for a custom control, what you
  5740. pass will depend on how the control is defined.
  5741.  
  5742.       - If actionProc is NIL, TrackControl performs no additional
  5743.         actions. This is appropriate for simple buttons, check boxes,
  5744.         radio buttons, and the thumb of a scroll bar.
  5745.  
  5746.       - ActionProc may be a pointer to an action procedure that defines
  5747.         some action to be performed repeatedly for as long as the user
  5748.         holds down the mouse button. (See below for details)
  5749.  
  5750.       - If actionProc is POINTER(-1), TrackControl looks in the control
  5751.         record for a pointer to the control's default action procedure. 
  5752.         If that field of the control record contains a procedure
  5753.         pointer, TrackControl uses the action procedure it points to; if
  5754.         the field contains POINTER(-1), TrackControl calls the control
  5755.         definition function to perform the necessary action. (If the
  5756.         field contains NIL, TrackControl does nothing.)
  5757.  
  5758.     The action procedure in the control definition function is described
  5759. in the section "Defining Your Own Controls". The following paragraphs
  5760. describe only the action procedure whose pointer is passed in the
  5761. actionProc parameter or stored in the control record.
  5762.  
  5763.     If the mouse button was pressed in an indicator, the action
  5764. procedure (if any) should have no parameters. This procedure must allow
  5765. for the fact that the mouse may not be inside the original control part.
  5766.  
  5767.     If the mouse button was pressed in a control part other than an
  5768. indicator, the action procedure should be of the form
  5769.  
  5770.     PROCEDURE MyAction (theControl: ControlHandle; partCode: INTEGER);
  5771.  
  5772.     In this case, TrackControl passes the control handle and the part
  5773. code to the action procedure. (It passes Ø in the partCode parameter if
  5774. the mouse has moved outside the original control part.)  As an example
  5775. of this type of action procedure, consider what should happen when the
  5776. mouse button is pressed in a scroll arrow or paging region in a scroll
  5777. bar. For these cases, your action procedure should examine the part
  5778. code to determine exactly where the mouse button was pressed, scroll up
  5779. or down a line or page as appropriate, and call SetCt1Value to change
  5780. the control's setting and redraw the thumb.
  5781.  
  5782. (warning)
  5783.     Since it has a different number of parameters depending
  5784.     on whether the mouse button was pressed in an indicator
  5785.     or elsewhere, the action procedure you pass to
  5786.     TrackControl (or whose pointer you store in the control
  5787.     record) can be set up for only one case or the other. If
  5788.     you store a pointer to a default action procedure in a
  5789.     control record, be sure it will be used only when
  5790.     appropriate for that type of action procedure. The only
  5791.     way to specify actions in response to all mouse-down
  5792.     events in a control, regardless of whether they're in an 
  5793.     indicator, is via the control definition function.
  5794. \ MoveControl
  5795. 6
  5796. PROCEDURE MoveControl (theControl: ControlHandle; h,v: INTEGER);
  5797.  
  5798.     MoveControl moves theControl to a new location within its window.
  5799. The top left corner of the control's enclosing rectangle is moved to the 
  5800. horizontal and vertical coordinates h and v (given in the local
  5801. coordinates of the control's window);  the bottom right corner is 
  5802. adjusted accordingly, to keep the size of the rectangle the same as
  5803. before. If the control is currently visible, it's hidden and then 
  5804. redrawn at its new location.
  5805.  
  5806. \ DragControl
  5807. 6
  5808. PROCEDURE DragControl (theControl: ControlHandle; startPt: Point;
  5809.                         limitRect,slopRect: Rect; axis: INTEGER);
  5810.  
  5811.     Called with the mouse button down inside theControl, DragControl
  5812. pulls a gray outline of the control around the screen, following the
  5813. movements of the mouse until the button is released. When the mouse
  5814. button is released, DragControl calls MoveControl to move the control
  5815. to the location to which it was dragged.
  5816.  
  5817. (note)
  5818.     Before beginning to follow the mouse, DragControl calls
  5819.     the control definition function to allow it to do its own
  5820.     "custom dragging" if it chooses. If the definition
  5821.     function doesn't choose to do any custom dragging, 
  5822.     DragControl uses the default method of dragging described
  5823.     here.
  5824.  
  5825.     DragControl calls the Window Manager utility function DragGrayRgn
  5826. and then moves the control accordingly. The startPt, limitRect,
  5827. slopRect, and axis parameters have the same meaning as for DragGrayRgn.
  5828. These parameters are reviewed briefly below; see the description of
  5829. DragGrayRgn in the Window Manager manual for more details.
  5830.  
  5831.       - StartPt parameter is assumed to be the point where the mouse
  5832.         button was originally pressed, in the local coordinates of the
  5833.         control's window. 
  5834.  
  5835.       - LimitRect limits the travel of the control's outline, and should 
  5836.         normally coincide with or be contained within the window's
  5837.         content region.
  5838.  
  5839.       - SlopRect allows the user some "slop" in moving the mouse; it
  5840.         should completely enclose limitRect.
  5841.  
  5842.       - The axis parameter allows you to constrain the control's motion to
  5843.         only one axis. It has one of the following values:
  5844.  
  5845.     CONST noConstraint  =   Ø;  {no constraint}
  5846.           hAxis Only    =   1;  {horizontal axis only}
  5847.           vAxis Only    =   2;  {vertical axis only}
  5848. \ SizeControl
  5849. 6
  5850. PROCEDURE SizeControl (theControl: ControlHandle; w,h: INTEGER);
  5851.  
  5852.     SizeControl changes the size of theControl's enclosing rectangle.
  5853. The bottom right corner of the rectangle is adjusted to set the
  5854. rectangle's width and height to the number of pixels specified by w and
  5855. h; the position of the top left corner is not changed. If the control
  5856. is currently visible, it's hidden and then redrawn in its new size.
  5857. \ SetCtlValue
  5858. 6
  5859. PROCEDURE SetCtlValue (theControl: ControlHandle; theValue: INTEGER);
  5860.  
  5861.     SetCtlValue sets theControl's current setting to theValue and
  5862. redraws the control to reflect the new setting. For check boxes and
  5863. radio buttons, the value 1 fills the control with the appropriate mark,
  5864. and Ø clears it. For scroll bars, SetCtlValue redraws the thumb where
  5865. appropriate.
  5866.  
  5867.     If the specified value is out of range, it's forced to the nearest 
  5868. endpoint of the current range (that is, if theValue is less than the
  5869. minimum setting, SetCtlValue sets the current setting to the minimum;
  5870. if theValue is greater than the maximum setting, it sets the current
  5871. setting to the maximum.
  5872. \ GetCtlValue
  5873. 6
  5874. FUNCTION GetCtlValue (theControl: ControlHandle) : INTEGER;
  5875.  
  5876.     GetCtlValue returns theControl's current setting. 
  5877. \ SetCtlMin
  5878. 6
  5879. PROCEDURE SetCtlMin (theControl: ControlHandle; minValue: INTEGER;
  5880.  
  5881.     SetCtlMin sets theControl's minimum setting to minValue and redraws
  5882. the control to reflect the new range. If the control's current setting
  5883. is less than minValue, the setting is changed to the new minimum.
  5884. \ GetCtlMin
  5885. 6
  5886. FUNCTION GetCtlMin (theControl: ControlHandle) : INTEGER;
  5887.  
  5888.     GetCtlMin returns theControl's minimum setting.
  5889. \ SetCtlMax
  5890. 6
  5891. PROCEDURE SetCtlMax (theControl: ControlHandle; maxValue: INTEGER);
  5892.  
  5893.     SetCtlMax sets theControl maximum setting to maxValue and redraws
  5894. the control to reflect the new range. If maxValue is less than the
  5895. control's current setting, the setting is changed to the new maximum.
  5896. \ GetCtlMax
  5897. 6
  5898. FUNCTION GetCtlMax (theControl: ControlHandle) : INTEGER;
  5899.  
  5900.     GetCtlMax returns theControl's maximum setting.
  5901. \ SetCRefCon
  5902. 6
  5903. PROCEDURE SetCRefCon (theControl: ControlHandle; data: LongInt);
  5904.  
  5905.     SetCRefCon sets theControl's reference value to the given data.
  5906. \ GetCRefCon
  5907. 6
  5908. FUNCTION GetCRefCon (theControl: ControlHandle) : LongInt;
  5909.  
  5910.     GetCRefCon returns theControl's current reference value.
  5911. \ SetCtlAction
  5912. 6
  5913. PROCEDURE SetCtlAction (theControl: ControlHandle; actionProc:
  5914.                         ProcPtr);
  5915.  
  5916.     SetCtlAction sets theControl's default action procedure to
  5917. actionProc.
  5918. \ GetCtlAction
  5919. 6
  5920. FUNCTION GetCtlAction (theControl: ControlHandle) : ProcPtr;
  5921.  
  5922.     GetCtlAction returns a pointer to theControl's default action 
  5923. procedure, if any. (It returns whatever is in that field of the
  5924. control record.)
  5925.  
  5926.  
  5927. The Control Definition Function
  5928. -------------------------------
  5929.  
  5930.     The control definition function may be written in Pascal or assembly
  5931. language; the only requirement is that its entry point must be at the
  5932. beginning. You can give your control definition function any name you
  5933. like. Here's how you would declare one named MyControl:
  5934.  
  5935.     FUNCTION MyControl (varCode: INTEGER; theControl; ControlHandle;
  5936.                         message: INTEGER; param: LongInt) : LongInt;
  5937.  
  5938. VarCode is the variation code, as described above.
  5939.  
  5940. TheControl is a handle to the control that the operation will affect.
  5941.  
  5942. The message parameter identifies the desired operation. It has one of
  5943. the following values:
  5944.  
  5945.   CONST drawCntl = Ø;   {draw the control (or control part)}
  5946.     testCntl     = 1;   {test where mouse button was pressed}
  5947.     calcCrgns    = 2;   {calculate control's region (or indicator's)}
  5948.     initCntl     = 3;   {do any additional control initialization}
  5949.     dispCntl     = 4;   {take any additional disposal actions}
  5950.     posCntl      = 5;   {reposition control's indicator and update it}
  5951.     thumbCntl    = 6;   {calculate parameters for dragging indicator}
  5952.     dragCntl     = 7;   {drag control (or its indicator)}
  5953.     autoTrack    = 8;   {execute control's action procedure}
  5954.  
  5955.     As described below in the discussions of the routines that perform
  5956. these operations, the value passed for param, the last parameter of the
  5957. control definition function, depends on the operation. Where it's not 
  5958. mentioned below, this parameter is ignored. Similarly, the control
  5959. definition function is expected to return a function result only where
  5960. indicated; in other cases, the function should return Ø.
  5961.  
  5962. (note)
  5963.     "Routine" here does not necessarily mean a procedure or
  5964.      function. While it's a good idea to set these up as 
  5965.      subprograms inside the control definition function,
  5966.      you're not required to do so.
  5967. \ UpdtControl
  5968. 6
  5969. PROCEDURE UpdtControl (theWindow: WindowPtr; updateRgn: RgnHandle);
  5970.  
  5971.     UpdtControl is a faster version of the DrawControls procedure.
  5972. Instead of drawing all of the controls in theWindow, UpdtControl
  5973. draws only the controls that are in the specified update region.
  5974. UpdtControl is called in response to an update event, and is usually
  5975. bracketed by calls to the Window Manager procedures BeginUpdate and
  5976. EndUpdate. UpdateRgn should be set to the visRgn of theWindow’s port
  5977. (for more details, see the BeginUpdate procedure in the Window Manager
  5978. chapter).
  5979.  
  5980. Note:  In general, controls are in a dialog box and are automatically
  5981. drawn by the DrawDialog procedure.
  5982. \ Draw1Control
  5983. 6
  5984. PROCEDURE Draw1Control (theControl: ControlHandle);
  5985.  
  5986.     Draw1Control draws the specified control if it’s visible within the
  5987. window.
  5988. \ InitMenus
  5989. 7
  5990. PROCEDURE InitMenus;
  5991.  
  5992.     InitMenus initializes the Menu Manager. It allocates space for the
  5993. menu list (a relocatable block on the heap large enough for the maximum
  5994. size menu list), and draws the (empty) menu bar. Call InitMenus once
  5995. before all other Menu Manager routines. An application should never
  5996. have to call this procedure more than once; to start afresh with all
  5997. new menus, use ClearMenuBar.
  5998.  
  5999. (note)
  6000.     The Window Manager initialization procedure InitWindows
  6001.     has already drawn the empty menu bar; InitMenus redraws
  6002.     it.
  6003. \ NewMenu
  6004. 7
  6005. FUNCTION NewMenu (menuID: INTEGER; MenuTitle: Str255) : MenuHandle;
  6006.  
  6007.     NewMenu allocates space for a new menu with the given menu ID and
  6008. title, and returns a handle to it. It sets up the menu to use the
  6009. standard menu definition procedure. The new menu (which is created
  6010. empty) is not installed in the menu list. To use this menu, you must
  6011. first call AppendMenu or AddResMenu to fill it with items, InsertMenu
  6012. to place it in the menu list, and DrawMenuBar to update the menu bar to
  6013. include the new title.
  6014.  
  6015.     Application menus should always have positive menu IDs. Negative
  6016. menu IDs are reserved for menus belonging to desk accessories. No menu
  6017. should ever have a menu ID of Ø.
  6018.  
  6019.     If you want to set up the title of the Apple menu from your program
  6020. instead of reading it in from a resource file, you can use the
  6021. predefined constant appleMark (equal to $14, the value of the apple
  6022. symbol). For example, you can declare the string variable
  6023.  
  6024.     VAR myTitle: STRING[1];
  6025.  
  6026. and do the following:
  6027.  
  6028.     myTitle := ' ';
  6029.     myTitle[1] := CHR(appleMark)
  6030.  
  6031.     To release the memory occupied by a menu that you created with
  6032. NewMenu, call DisposeMenu.
  6033. \ GetMenu
  6034. 7
  6035. FUNCTION GetMenu (resourceID: INTEGER) : MenuHandle;
  6036.  
  6037.     GetMenu returns a menu handle for the menu having the given resource
  6038. ID. It calls the Resource Manager to read the menu from the resource
  6039. file into a menu record in memory. It stores the handle to the menu
  6040. definition procedure in the menu record, reading the procedure from the
  6041. resource file into memory if necessary. To use this menu, you must
  6042. call InsertMenu to place it in the menu list and DrawMenuBar to update
  6043. the menu bar to include the new title.
  6044.  
  6045. (warning)
  6046.     Only call GetMenu once for a particular menu. If you
  6047.     need the menu handle to a menu that's already in memory, 
  6048.     use the Resource Manager function GetResource.
  6049.  
  6050.     To release the memory occupied by a menu that you read from a
  6051. resource file with GetMenu, use the Resource Manager procedure
  6052. ReleaseResource.
  6053. \ DisposeMenu
  6054. 7
  6055. PROCEDURE DisposeMenu (theMenu: MenuHandle);
  6056.  
  6057.     Call DisposeMenu to release the memory occupied by a menu that you
  6058. allocated with NewMenu. (For menus read from a resource file with
  6059. GetMenu, use the Resource Manager procedure ReleaseResource instead.)
  6060. This is useful if you've created temporary menus that you no longer
  6061. need.
  6062.  
  6063. (warning)
  6064.     Make sure you remove the menu from the menu list (with
  6065.     DeleteMenu) before disposing of it. Also be careful not
  6066.     to use the menu handle after disposing of the menu.
  6067.  
  6068.  
  6069. \ AppendMenu
  6070. 7
  6071. PROCEDURE AppendMenu (theMenu: MenuHandle; data: Str255);
  6072.  
  6073.     AppendMenu adds an item or items to the end of the given menu, which
  6074. must previously have been allocated by NewMenu or read from a resource
  6075. file by GetMenu. The data string consists of the text of the menu
  6076. item; it may be blank but should not be the null string. If it begins
  6077. with a hyphen (-), the item will be a dividing line across the width of
  6078. the menu. As described in the section "Creating a Menu in Your 
  6079. Program", the following meta-characters may be embedded in the data
  6080. string:
  6081.  
  6082.    Meta-character     Usage
  6083.    --------------     -----
  6084.  
  6085.     ; or Return       Separates multiple items
  6086.     ^                 Followed by an icon number, adds that icon to
  6087.                       the item
  6088.     !                 Followed by a character, marks the item with
  6089.                       that character
  6090.     <                 Followed by B, I, U, O, or S, sets the
  6091.                       character style of the item
  6092.     /                 Followed by a character, associates a keyboard
  6093.                       equivalent with the item
  6094.     (                 Disables the item
  6095.  
  6096.     Once items have been appended to a menu, they cannot be removed or
  6097. rearranged. AppendMenu works properly whether or not the menu is in
  6098. the menu list.
  6099. \ AddResMenu
  6100. 7
  6101. PROCEDURE AddResMenu (theMenu: MenuHandle; theType: ResType);
  6102.  
  6103.     AddResMenu searches all open resource files for resources of type
  6104. theType and appends the names of all resources it finds to the given
  6105. menu. Each resource name appears in the menu as an enabled item,
  6106. without an icon or mark, and in the normal character style. The
  6107. standard Menu Manager calls can be used to get the name or change its
  6108. appearance, as described below under "Controlling Items' Appearance".
  6109.  
  6110. (note)
  6111.     So that you can have resources of the given type that
  6112.     won't appear in the menu, any resource names that begin 
  6113.     with a period (.) or a percent sign (%) aren't apppended 
  6114.     by AddResMenu.
  6115.  
  6116.     Use this procedure to fill a menu with the names of all available
  6117. fonts or desk accessories. For example, if you declare a variable as
  6118.  
  6119.     VAR fontMenu: MenuHandle;
  6120.  
  6121. you can set up a menu containing all font names as follows:
  6122.  
  6123.     fontMenu := NewMenu(5,'Fonts');
  6124.     AddResMenu(fontMenu,"FONT')
  6125. \ InsertResMenu
  6126. 7
  6127. Procedure InsertResMenu (theMenu: MenuHandle; theType: ResType;
  6128.                         afterItem: INTEGER);
  6129.  
  6130.     InsertResMenu is the same as AddRes˜enu (above) except that it
  6131. inserts the resource names in the menu where specified by the afterItem
  6132. parameter:  if afterItem is Ø, the names are inserted before the first
  6133. menu item; if it's the item number of an item in the menu, they're
  6134. inserted after that item; if it's equal to or greater than the last
  6135. item number, they're appended to the menu.
  6136.  
  6137. (note)
  6138.     InsertResMenu inserts the names in the reverse of the
  6139.     order that AddResMenu appends them. For consistency
  6140.     between the applications in the appearance of menus, use
  6141.     AddResMenu instead of InsertResMenu if possible.
  6142. \ InsertMenu
  6143. 7
  6144. PROCEDURE InsertMenu (theMenu: MenuHandle; before ID: INTEGER);
  6145.  
  6146.     InsertMenu inserts a menu into the menu list before the menu whose
  6147. menu ID equals beforeID. If beforeID is Ø (or isn't the ID of any menu
  6148. in the menu list), the new menu is added after all others. If the menu
  6149. is already in the menu list or the menu list is already full, InsertMenu
  6150. does nothing. Be sure to call DrawMenuBar to update the menu bar.
  6151. \ DrawMenuBar
  6152. 7
  6153. PROCEDURE DrawMenuBar;
  6154.  
  6155.     DrawMenuBar redraws the menu bar according to the menu list,
  6156. incorporating any changes since the last call to DrawMenuBar. Any
  6157. highlighted menu title remains highlighted when drawn by DrawMenuBar.
  6158. This procedure should always be called after a sequence of InsertMenu
  6159. or DeleteMenu calls, and after ClearMenuBar, SetMenuBar, or any other
  6160. routine that changes the menu list.
  6161. \ DeleteMenu
  6162. 7
  6163. PROCEDURE DeleteMenu (menuID: INTEGER);
  6164.  
  6165.     DeleteMenu deletes a menu from the menu list. If there's no menu
  6166. with the given menu ID in the menu list, DeleteMenu has no effect. Be
  6167. sure to call DrawMenuBar to update the menu bar; the menu titles
  6168. following the deleted menu will move over to fill the vacancy.
  6169.  
  6170. (note)
  6171.     DeleteMenu simply removes the menu from the list of
  6172.     currently available menus; it doesn't release the memory 
  6173.     occupied by the menu data structure.
  6174. \ ClearMenuBar
  6175. 7
  6176. PROCEDURE ClearMenuBar;
  6177.  
  6178.  
  6179.     Call ClearMenuBar to remove all menus from the menu list when you
  6180. want to start afresh with all new menus. Be sure to call DrawMenuBar to
  6181. update the menu bar.
  6182.  
  6183. (note)
  6184.     ClearMenuBar, like Delete Menu, doesn't release the memory 
  6185.     occupied by the menu data structures; it merely removes
  6186.     them from the menu list.
  6187.  
  6188.     You don't have to call ClearMenuBar at the beginning of your
  6189. program, because InitMenus clears the menu list for you.
  6190. \ GetNewMBar
  6191. 7
  6192. FUNCTION GetNewMBar (menuBarID: INTEGER) : Handle;
  6193.  
  6194.     GetNewMBar creates a menu list as defined by the menu bar resource
  6195. having the given resource ID, and returns a handle to it. If the
  6196. resource isn't already in memory, GetNewMBar reads it into memory from 
  6197. the resource file. It calls GetMenu to get each of the individual
  6198. menus.
  6199.  
  6200.     To make the menu list created by  GetNew˜Bar the  current menu list,
  6201. call SetMenuBar. To release the memory occupied by the menu list, use
  6202. the Memory Manager procedure DisposHandle.
  6203.  
  6204. (warning)
  6205.  
  6206.     You don't have to know the indivudual menu IDs to use 
  6207.     GetNewMBar, but that doesn't mean you don't have to know
  6208.     them at all:  to do anything further with a particular
  6209.     menu, you have to know its ID or its handle (which you
  6210.     can get by passing the ID to GetMHandle, as described
  6211.     below under "Miscellaneous Routines").
  6212.  
  6213.  
  6214. \ GetMenuBar
  6215. 7
  6216. FUNCTION GetMenuBar : Handle;
  6217.  
  6218.     GetMenuBar creates a copy of the current menu list and returns a
  6219. handle to the copy. You can then add or remove menus from the menu list
  6220. (with InsertMenu, DeleteMenu, or ClearMenuBar), and later restore the
  6221. saved menu list with SetMenuBar. To release the memory occupied by the
  6222. saved menu list, use the Memory Manager procedure DisposHandle.
  6223.  
  6224. (warning)
  6225.     GetMenuBar doesn't copy the menus themselves, only a list 
  6226.     containing their handles. Do not dispose of any menus
  6227.     that might be in a saved menu list.
  6228. \ SetMenuBar
  6229. 7
  6230. PROCEDURE SetMenuBar (menuList: Handle);
  6231.  
  6232.     SetMenuBar copies the given menu list to the current menu list. You
  6233. can use this procedure to restore a menu list previously saved by
  6234. GetMenuBar, or pass it a handle returned by GetNewMBar. Be sure to
  6235. call DrawMenuBar to update the menu bar.
  6236. \ MenuSelect
  6237. 7
  6238. FUNCTION MenuSelect (startPt: Point) : LONGINT;
  6239.  
  6240.     When there's a mouse-down event in the menu bar, the application
  6241. should call MenuSelect with startPt equal to the point (in global
  6242. coordinates) where the mousebutton was pressed.  MenuSelect keeps
  6243. control until the mouse button is released, tracking the mouse, pulling
  6244. down menus as needed, and highlighting enabled menu items under the
  6245. cursor. When the mouse button is released over an enabled item in an
  6246. application menu, MenuSelect returns a long integer whose high-order
  6247. word is the menu ID of the menu, and whose low-order word is the menu
  6248. item number for the item chosen (see Figure 3). It leaves the selected
  6249. menu title highlighted. After performing the chosen task, your
  6250. application should call HiliteMenu(Ø) to remove the highlighting from
  6251. the menu title.
  6252.  
  6253.     If no choice is made, MenuSelect returns Ø in the high-order word of
  6254. the long integer, and the low-order word is undefined. This includes
  6255. the case where the mouse button is released over a disabled menu item
  6256. (such as Cut, Copy, Clear, or one of the dividing lines in Figure 3),
  6257. over any menu title, or outside the menu.
  6258.  
  6259.     If the mouse button is released over an enabled item in a menu
  6260. belonging to a desk accessory, MenuSelect passes the menu ID and item
  6261. number to the Desk Manager procedure SystemMenu for processing, and
  6262. returns Ø to your application in the high-order word of the result.
  6263. \ MenuKey
  6264. 7
  6265. FUNCTION MenuKey (ch: CHAR) : LONGINT;
  6266.  
  6267.     MenuKey maps the given character to the associated menu and item for
  6268. that character. When you get a key-down event with the Command key
  6269. held down--or an auto-key event, if the command being invoked is
  6270. repeatable--call MenuKey with the character that was typed. MenuKey
  6271. highlights the appropriate menu title, and returns a long integer
  6272. containing the menu ID in its high-order word and the menu item number
  6273. in its low-order word, just as MenuSelect does (see Figure 3 above).
  6274. After performing the chosen task, your application should call
  6275. HiliteMenu(Ø) to remove the highlighting from the menu title.
  6276.  
  6277.     If the given character isn't associated with any enabled menu item 
  6278. currently in the menu list, MenuKey returns Ø in the high-order word of
  6279. the long integer, and the low-order word is undefined.
  6280.  
  6281.     If the given character involes a menu item in a menu belonging to a
  6282. desk accessory, MenuKey (like MenuSelect) passes the menu ID and item
  6283. number to the Desk Manager procedure SystemMenu for processing, and
  6284. returns Ø to your application in the high-order word of the result.
  6285.  
  6286. (note)
  6287.     There should never be more than one item in the menu list
  6288.     with the same keyboard equivalent, but if there is,
  6289.     MenuKey returns the first such item it encounters,
  6290.     scanning the menus from right to left and their items
  6291.     from top to bottom.
  6292. \ HiliteMenu
  6293. 7
  6294. PROCEDURE HiliteMenu (menuID: INTEGER);
  6295.  
  6296.     Hilite Menu highlights the title of the given menu, or does nothing
  6297. if the title is already highlighted. Since only one menu title can be
  6298. highlighted at a time, it unhighlights any previously highlighted menu
  6299. title. If MenuID is Ø (or isn't the ID of any menu in the menu list),
  6300. HiliteMenu simply unhighlights whichever menu title is highlighted (if
  6301. any).
  6302.  
  6303.     After MenuSelect or MenuKey, your application should perform the
  6304. chosen task and then call HiliteMenu(Ø) to unhighlight the chosen menu
  6305. title.
  6306. \ SetItem
  6307. 7
  6308. PROCEDURE SetItem (theMenu: MenuHandle; item: INTEGER; itemString:
  6309.     Str255);
  6310.  
  6311.     SetItem changes the text of the given menu item to itemString. It
  6312. doesn't recognize the meta-characters used in AppendMenu; if you
  6313. include them in itemString, they will appear in the text of the menu
  6314. item. The attributes already in effect for this item--its character
  6315. style, icon, and so on--remain in effect. ItemString may be blank but
  6316. should not be the null string.
  6317.  
  6318. (note)
  6319.     It's good practice to store the text of itemString in a 
  6320.     resource file instead of passing it directly.
  6321.  
  6322.     Use SetItem to flip between two alternative menu items--for example,
  6323. to change "Show Clipboard" top "Hide Clipboard" when the Clipboard is
  6324. already showing.
  6325.  
  6326. (note)
  6327.     To avoid confusing the user, don't capriciously change 
  6328.     the text of menu items.
  6329. \ GetItem
  6330. 7
  6331. PROCEDURE GetItem (theMenu: MenuHandle; item: INTEGER; VAR itemString:
  6332.     Str255);
  6333.  
  6334.     GetItem returns the text of the given menu item in itemString. It
  6335. doesn't place any meta-characters in the string. This procedure is 
  6336. useful for getting the name of a menu item that was installed with
  6337. AddResMenu or InsertResMenu.
  6338. \ DisableItem
  6339. 7
  6340. PROCEDURE DisableItem (theMenu: MenuHandle; item: INTEGER);
  6341.  
  6342.     Given a menu item number in the item parameter, DisableItem disables
  6343. that menu item; given Ø in the item parameter, it disables the entire
  6344. menu.
  6345.  
  6346.     Disabled menu items appear dimmed and are not highlighted when the
  6347. cursor moves over them. MenuSelect and MenuKey return Ø in the high-
  6348. order word of their result if the user attempts to invoke a disabled
  6349. item. Use DisableItem to disable all menu choices that aren't
  6350. appropriate at a given time (such as a Cut command when there's no text
  6351. selection).
  6352.  
  6353.     All menu items are initially enabled unless you specify otherwise
  6354. (such as by using the "(" meta-character in a call to AppendMenu).
  6355.  
  6356.     Every menu item in a disabled menu is dimmed. The menu title is
  6357. also dimmed, but you must call DrawMenuBar to update the menu bar to
  6358. show the dimmed title.
  6359. \ EnableItem
  6360. 7
  6361. PROCEDURE EnableItem (theMenu:  MenuHandle; item: INTEGER);
  6362.  
  6363.     Given a menu item number in the item parameter, EnableItem enables
  6364. the item; given 0 in the item parameter, it enables the entire menu.
  6365. (The item or menu may have been disabled with the DisableItem procedure,
  6366. or the item may have been disabled with the "(" meta-character in the
  6367. AppendMenu string.)  The item or menu title will no longer appear
  6368. dimmed and can be chosen like any other enabled item or menu.
  6369. \ CheckItem
  6370. 7
  6371. PROCEDURE CheckItem (theMenu:  MenuHandle; item:  INTEGER; checked:
  6372.             BOOLEAN);
  6373.  
  6374.     CheckItem places or removes a check mark at the left of the given
  6375. menu item. After you call CheckItem with checked=TRUE, a check mark
  6376. will appear each subsequent time the menu is pulled down. Calling
  6377. CheckItem with checked=FALSE removes the check mark from the menu item
  6378. (or, if it's marked with a different character, removes that mark).
  6379.  
  6380.     Menu items are initially unmarked unless you specify otherwise (such
  6381. as with the "!" meta-character in a call to AppendMenu).
  6382. \ SetItemMark
  6383. 7
  6384. PROCEDURE SetItemMark (theMenu: MenuHandle; item: INTEGER; markChar:
  6385.              CHAR);
  6386.  
  6387.     SetItemMark marks the given menu item in a more general manner than
  6388. CheckItem. It allows you to place any character in the system font,
  6389. not just the check mark, to the left of the item. You can specify some
  6390. useful values for the markChar parameter with the following predefined
  6391. constants:
  6392.  
  6393.        CONST noMark      = 0;      {NUL character, to remove a mark}
  6394.              commandMark = $11;    {Command key symbol}
  6395.              checkMark   = $12;    {check mark}
  6396.              diamondMark = $13;    {diamond symbol}
  6397.              appleMark   = $14;    {apple symbol}
  6398. \ GetItemMark
  6399. 7
  6400. PROCEDURE GetItemMark (theMenu: MenuHandle; item: INTEGER; VAR
  6401.             markChar: CHAR);
  6402.  
  6403.     GetItemMark returns in markChar whatever character the given menu
  6404. item is marked with, or the NUL character (ASCII code 0) if no mark is
  6405. present.
  6406. \ SetItemIcon
  6407. 7
  6408. PROCEDURE SetItemIcon (theMenu: MenuHandle; item: INTEGER; icon: Byte);
  6409.  
  6410.     SetItemIcon associates the given menu item with an icon. It sets
  6411. the item's icon number to the given value (an integer from 1 to 255).
  6412. The Menu Manager adds 256 to the icon number to get the icon's resource
  6413. ID, which it passes to the Resource Manager to get the corresponding
  6414. icon.
  6415.  
  6416. (warning)
  6417.        If you deal directly with the Resource Manager to read or
  6418.        store menu icons, be sure to adjust your icon numbers
  6419.        accordingly.
  6420.  
  6421. Menu items initially have no icons unless you specify otherwise (such
  6422. as with the "^" meta-character in a call to AppendMenu).
  6423. \ GetItemIcon
  6424. 7
  6425. PROCEDURE GetItemIcon (theMenu: MenuHandle; item: INTEGER; VAR icon:
  6426.                          Byte);
  6427.  
  6428.     GetItemIcon returns the icon number associated with the given menu
  6429. item, as an integer from 1 to 255, or 0 if the item has not been
  6430. associated with an icon. The icon number is 256 less than the icon's 
  6431. resource ID.
  6432. \ SetItemStyle
  6433. 7
  6434. PROCEDURE SetItemStyle (theMenu: MenuHandle; item: INTEGER; chStyle:
  6435.                         Style);
  6436.  
  6437.     SetItemStyle changes the character style of the given menu item to
  6438. chStyle. For example:
  6439.  
  6440.     SetItemStyle(thisMenu,1,[bold,italic])     {bold and italic}
  6441.  
  6442.     Menu items are initially in the normal character style unless you
  6443. specify otherwise (such as with the "<" meta-character in a call to
  6444. AppendMenu).
  6445. \ GetItemStyle
  6446. 7
  6447. PROCEDURE GetItemStyle (theMenu: MenuHandle; item: INTEGER; VAR
  6448.                         chStyle: Style);
  6449.  
  6450.     GetItemStyle returns the character style of the given menu item in
  6451. chStyle.
  6452. \ CalcMenuSize
  6453. 7
  6454. PROCEDURE CalcMenuSize (theMenu: MenuHandle);
  6455.  
  6456.     You can use CalcMenuSize to recalculate the horizontal and vertical
  6457. dimensions of a menu whose contents have been changed (and store them
  6458. in the appropriate fields of the menu record). CalcMenuSize is called
  6459. internally by the Menu Manager after every AppendMenu, SetItem,
  6460. SetItemIcon, and SetItemStyle call.
  6461. \ CountMItems
  6462. 7
  6463. FUNCTION CountMItems (TheMenu: MenuHandle): INTEGER;
  6464.  
  6465.     CountMItems returns the number of menus item in the given menu.
  6466. \ GetMHandle
  6467. 7
  6468. FUNCTION GetMHandle (menuID: INTEGER) : MenuHandle;
  6469.  
  6470.     Given the menu ID of a menu currently installed in the menu list,
  6471. GetMHandle returns a handle to that menu; given any other menu ID, it
  6472. returns NIL.
  6473. \ FlashMenuBar
  6474. 7
  6475. PROCEDURE FlashMenuBar (menuID: INTEGER);
  6476.  
  6477.     If menuID is 0 (or isn't the ID of any menu in the menu list),
  6478. FlashMenuBar inverts the entire menu bar; otherwise, it inverts the
  6479. title of the given menu.
  6480. \ SetMenuFlash
  6481. 7
  6482. PROCEDURE SetMenuFlash (count: INTEGER);
  6483.  
  6484.     When the mouse button is released over an enabled menu item, the
  6485. item blinks briefly to confirm the choice. Normally your application
  6486. shouldn't be concerned with this blinking; the user sets it with the
  6487. Control Panel desk accessory. If you're writing a desk accessory like
  6488. the Control Panel, though, SetMenuFlash allows you to control the
  6489. duration of this blinking. Count is the number of times menu items
  6490. will blink; it's initially 3 if the user hasn't changed it. A count of
  6491. 0 disables blinking. Values greater than 3 can be annoyingly slow.
  6492.  
  6493. (warning)
  6494.     Don't call SetMenuFlash from your main program.     
  6495.  
  6496. (note)
  6497.     Items in both standard and nonstandard menus blink when
  6498.     chosen. The appearance of the blinking for a nonstandard
  6499.     menu depends on the menu definition procedure, as
  6500.     described below.
  6501. \ InsMenuItem
  6502. 7
  6503. PROCEDURE InsMenuItem (theMenu: MenuHandle; itemString: Str255; afterItem: INTEGER);
  6504.  
  6505.     InsMenuItem inserts an item or items into the given menu where
  6506. specified by the afterItem parameter. If afterItem is 0, the items
  6507. are inserted before the first menu item; if it’s the item number of an
  6508. item in the menu, they’re inserted after that item; if it’s equal to or
  6509. greater than the last item number, they’re appended to the menu.
  6510.  
  6511. Warning:  Only the items contained in itemString are sorted.
  6512.  
  6513.     The contents of itemString are parsed as in the AppendMenu
  6514. procedure. Multiple items are inserted in the reverse of their order in
  6515. itemString.
  6516. \ DelMenuItem
  6517. 7
  6518. PROCEDURE DelMenuItem (theMenu: MenuHandle; item: INTEGER);
  6519.  
  6520.     DelMenuItem deletes the specified item from the given menu.
  6521.  
  6522. Note:  DelMenuItem is intended for maintaining dynamic menus (such as
  6523.        a list of open windows). It should not be used for disabling
  6524.        items; you should use DisableItem instead.
  6525. \ TEInit
  6526. 8
  6527. PROCEDURE TEInit;
  6528.  
  6529.     TEInit initializes TextEdit by allocating a handle for the TextEdit
  6530. scrap. The scrap is initially empty. Calll this procedure once and
  6531. only once at the beginning of your program.
  6532.  
  6533. (note)
  6534.       You should call TEInit even if your application doesn't
  6535.       use TextEdit, so that desk accessories and dialog and
  6536.       alert boxes will work correctly.
  6537. \ TENew
  6538. 8
  6539. FUNCTION TENew (destRect, viewRect: Rect) : TEHandle;
  6540.  
  6541.     TENew allocates a handle for the text, creates and initializes an
  6542. edit record, and returns a handle to the new edit record. DestRect and
  6543. viewRect are the destination and view rectangles, respectively. Both
  6544. rectangles are specified in the current grafPort's coordinates. The
  6545. destination rectangle must always be at least as wide as the first
  6546. character drawn (about 20 pixels is usually a good width). The view
  6547. rectangle must not be empty (for example, don't make its right edge
  6548. less than its left edge if you don't want any text visible--specify a 
  6549. rectangle off the screen instead).
  6550.  
  6551.     Call TENew once for every edit record you want allocated. The edit
  6552. record incorporates the drawing environment of the grafPort, and is
  6553. initialized for left-justified, single-spaced text with an insertion
  6554. point at character position 0.
  6555.  
  6556. (note)
  6557.       The caret won't appear until you call TEActivate.
  6558. \ TEDispose
  6559. 8
  6560. PROCEDURE TEDispose (hTE: TEHandle);
  6561.  
  6562.     TEDispose releases the memory allocated for the edit record and text
  6563. specified by hTE. Call this procedure when you're completely through
  6564. with an edit record.
  6565. \ TESetText
  6566. 8
  6567. PROCEDURE TESetText (text: Ptr; length: LONGINT; hTE: TEHandle);
  6568.  
  6569.     TESetText incorporates a copy of the specified text into the edit
  6570. record specified by hTE. The text parameter points to the text, and
  6571. the length paramenter indicates the number of characters in the text.
  6572. The selection range is set to an insertion point at the end of the
  6573. text. TESetText doesn't affect the text drawn in the destination
  6574. rectangle, so call TEUpdate afterward if necessary. TESetText doesn't 
  6575. dispose of any text currently in the edit record.
  6576. \ TEGetText
  6577. 8
  6578. FUNCTION TEGetText (hTE: TEHandle) : CharsHandle;
  6579.  
  6580.     TEGetText returns a handle to the text of the specified edit record.
  6581. The result is the same as the handle in the hText field of the edit
  6582. record, but has the CharsHandle data type, which is defined as:
  6583.  
  6584.        TYPE CharsHandle = ^CharsPtr;
  6585.             CharsPtr    = ^Chars;
  6586.         Chars       =PACKED ARRAY{0..3200] OF CHAR;
  6587.  
  6588.     You can get the length of the text from the teLength field of the
  6589. edit record.
  6590. \ TEIdle
  6591. 8
  6592. PROCEDURE TEIdle (hTE: TEHandle);
  6593.  
  6594.     Call TEIdle repeatedly to make a blinking caret appear at the
  6595. insertion point (if any) in the text specified by hTE. (The caret
  6596. appears only when the window containing that text is active, of course.)
  6597. TextEdit observes a minimum blink interval:  No mater how often  you
  6598. call TEIdle, the time between blinks will never be less than the
  6599. minimum interval.
  6600.  
  6601. (note)
  6602.       You actually need to call TEIdle only when the window
  6603.       containing the text is active.
  6604. \ TEClick
  6605. 8
  6606. PROCEDURE TEClick (pt: Point; extend: BOOLEAN; hTE: TEHandle);
  6607.  
  6608.     TEClick controls the placement and highlighting of the selection
  6609. range as determined by mouse events. Call TEClick whenever a mouse-down
  6610. event occurs in the view rectangle of the edit record specified by hTE,
  6611. and the window associated with that edit record is active. TEClick
  6612. keeps control until the mouse button is released. Pt is the mouse
  6613. location (in local coordinates) at the time the button was pressed,
  6614. obtainable from the event record.
  6615.  
  6616. (note)
  6617.       Use the QuickDraw procedure GlobalToLocal to convert the
  6618.       global coordinates of the mouse location given in the
  6619.       event record to the local coordinate system for pt.
  6620.  
  6621.     Pass TRUE for the extend parameter if the Event Manager indicates
  6622. that the Shift key was held down at the time of the click (to extend the
  6623. selection).
  6624.  
  6625.     TEClick unhighlights the old selection range unless the selection
  6626. range is being extended. If the mouse moves, meaning that a drag is
  6627. occurring, TEClick expands or shortens the selection range accordingly.
  6628. In the case of a double-click, the word under the cursor becomes the
  6629. selection range; dragging expands or shortens the selection a word at a
  6630. time.
  6631. \ TESetSelect
  6632. 8
  6633. PROCEDURE TESetSelect (selStart,selEnd: LONGINT; hTE: TEHandle);
  6634.  
  6635.     TESetSelect sets the selection range to the text between selStart
  6636. and selEnd in the text specified by hTE. The old selection range is
  6637. unhighlighted, and the new one is highlighted. If selStart equals
  6638. selEnd, the selection range is an insertion point, and a caret is
  6639. displayed
  6640.  
  6641.     SelEnd and selStart can range from 0 to 32767. If selEnd is
  6642. anywhere beyond the last character of the text, the position just past
  6643. the last character is used.
  6644. \ TEActivate
  6645. 8
  6646. PROCEDURE TEActivate (hTE: TEHandle);
  6647.  
  6648.     TEActivate highlights the selection range in the view rectangle of
  6649. the edit record specified by hTE. If the selection range is an
  6650. insertion point, it displays a caret there. This procedure should be
  6651. called every time the Toolbox Event Manager function GetNextEvent
  6652. reports that the window containing the edit record has become active.
  6653. \ TEDeactivate
  6654. 8
  6655. PROCEDURE TEDeactivate (hTE: TEHandle);
  6656.  
  6657.     TEDeactivate unhighlights the selection range in the view rectangle
  6658. of the edit record specified by hTE. If the selection range is an
  6659. insertion point, it removes the caret. This procedure should be called
  6660. every time the Toolbox Event Manager function GetNextEvent reports that
  6661. the window containing the edit record has become inactive.
  6662. \ TEKey
  6663. 8
  6664. PROCEDURE TEKey (key: CHAR; hTE: TEHandle);
  6665.  
  6666.     TEKey replaces the selection range in the text specified by hTE with
  6667. the character given by the key parameter, and leaves an insertion point
  6668. just past the inserted character. If the selection range is an
  6669. insertion point, TEKey just inserts the character there. If the key
  6670. parameter contains a Backspace character, the selection range or the
  6671. character immediately to the left of the insertion point is deleted.
  6672. TEKey redraws the text as necessary. Call TEKey every time the Toolbox
  6673. Event Manager function GetNextEvent reports a keyboard event that your
  6674. application decides should be handled by TextEdit.
  6675.  
  6676. (note)
  6677.       TEKey inserts every character passed in the key
  6678.       parameter, so it's up to your application to filter out
  6679.       all characters that aren't actual text (such as keys
  6680.       typed in conjuction with the Command key).
  6681. \ TECut
  6682. 8
  6683. PROCEDURE TECut (hTE: TEHandle);
  6684.  
  6685.     TECut removes the selection range from the text specified by hTE and
  6686. places it in the TextEdit scrap. The text is redrawn as necessary.
  6687. Anything previously in the scrap is lost. (See Figure 6.)  If the
  6688. selection range is an insertion point, the scrap is emptied.
  6689. \ TECopy
  6690. 8
  6691. PROCEDURE TECopy (hTE: TEHandle);
  6692.  
  6693.     TECopy copies the selection range from the text specified by hTE
  6694. into the TextEdit scrap. Anything previously in the scrap is deleted.
  6695. The selection range is not deleted. If the selection range is an
  6696. insertion point, the scrap is emptied.
  6697. \ TEPaste
  6698. 8
  6699. PROCEDURE TEPaste (hTE: TEHandle);
  6700.  
  6701.     TEPaste replaces the selection range in the text specified by hTE
  6702. with the contents of the TextEdit scrap, and leaves an insertion point
  6703. just past the inserted text. (See Figure 7.)  The text is redrawn as
  6704. necessary. If the scrap is empty, the selection range is deleted. If
  6705. the selection range is an insertion point, TEPaste just inserts the
  6706. scrap there.
  6707. \ TEDelete
  6708. 8
  6709. PROCEDURE TEDelete (hTE: TEHandle);
  6710.  
  6711.     TEDelete removes the selection range from the text specified by hTE,
  6712. and redraws the text as necessary. TEDelete is the same as TECut
  6713. (above) except that it doesn't transfer the selection range to the
  6714. scrap. If the selection range is an insertion point, nothing happens.
  6715. \ TEInsert
  6716. 8
  6717. PROCEDURE TEInsert (text: Ptr; length: LONGINT; hTE: TEHandle);
  6718.  
  6719.     TEInsert takes the specified text and inserts it just before the
  6720. selection range into the text indicated by hTE, redrawing the text as
  6721. necessary. The text parameter points to the text to be inserted, and
  6722. the length parameter indicates the number of characters to be inserted.
  6723. TEInsert doesn't affect either the current  selection range or the
  6724. scrap.
  6725. \ TESetJust
  6726. 8
  6727. PROCEDURE TESetJust (just: INTEGER, hTE: TEHandle);
  6728.  
  6729.     TESetJust sets the justification of the text specified by hTE to
  6730. just. (See"Justification" under "Edit Records".)  TextEdit provides
  6731. three predefined constants for setting justification:
  6732.  
  6733.         CONST: teJustLeft   = 0;
  6734.                teJustCenter = 1;
  6735.                teJustRight  = -1;
  6736.  
  6737.     By default, text is left-justified. If you change the
  6738. justification, call TEUpdate after TESetJust, to redraw the text with
  6739. the new justification.
  6740. \ TEUpdate
  6741. 8
  6742. PROCEDURE TEUpdate (rUpdate: Rect; hTE: TEHandle);
  6743.  
  6744.     TEUpdate draws the text specified by hTE within the rectangle
  6745. specified by rUpdate. The rUpdate rectangle must be given in the
  6746. coordinates of the current grafPort. Call TEUpdate every time the
  6747. Tolbox Event Manager function GetNextEvent reports an update event for a
  6748. text editing window--after you call the Window Manager procedure
  6749. BeginUpdate, and before you call EndUpdate.
  6750.  
  6751. Normally you'll do the following when an update event occurs:
  6752.  
  6753.        BeginUpdate(myWindow);
  6754.        EraseRect(myWindow^.portRect);
  6755.        TEUpdate(myWindow^I.protRect,hTE);
  6756.        EndUpdate(myWindow)
  6757.  
  6758.     If you don't include the EraseRect call, the caret may sometimes
  6759. remain visible when the window is deactivated.
  6760. \ TextBox
  6761. 8
  6762. PROCEDURE TextBox (text: Ptr; length: LONGINT; box: Rect; just:
  6763.             INTEGER);
  6764.  
  6765.     TextBox draws the specified text in the rectangle indicated by the
  6766. box parameter with justification just. (See "justification" under "Edit
  6767. Records".)  The text parameter points to the text, and the length
  6768. parameter indicates the number of characters to draw. The rectangle is
  6769. specified in local coordinates, that must be at least as wide as the
  6770. first character drawn (about 20 pixels is usually a good width).
  6771. TextBox does not create an edit record, nor can the text that it draws
  6772. be edited; it's used solely for drawing text. For example:
  6773.  
  6774.     str := 'String in a box';
  6775.     SetRect(r,100,100,200,200);
  6776.     TextBox(POINTER(ORD(@str)+1),LENGTH(str),r,teJustCenter);
  6777.     FrameRect(r)
  6778.  
  6779.     Because Pascal strings start with a length byte, you must advance
  6780. the pointer one position past the beginning of the string to point to
  6781. the start of the text.
  6782. \ TEScroll
  6783. 8
  6784. PROCEDURE TEScroll (dh,dv: INTEGER; hTE: TEHandle);
  6785.  
  6786.     TEScroll scrolls the text within the view rectangle of the specified
  6787. edit record by the number of pixels specified in the dh and dv
  6788. parameters. The edit record is specified by the hTE parameter.
  6789. Positive dh and dv values move the text right and down, respectively,
  6790. and negative values move the text left and up. For example,
  6791.  
  6792.      TEScroll(0,-hTE^^.lineHeight,hTE)
  6793.  
  6794. scrolls the text up one line. Remember that you scroll text up when
  6795. the user clicks in the scroll arrow pointing down. The destination
  6796. rectangle is offset by the amount you scroll.
  6797.  
  6798. (note)
  6799.       To implement automatic scrolling, you store the address
  6800.       of a routine in the clikLoop field of the edit record, as
  6801.       described above under "The TERec Data Type".
  6802. \ TEFromScrap
  6803. 8
  6804. FUNCTION TEFromScrap : OSErr;  [Not in ROM]
  6805.  
  6806.     TEFromScrap copies the desk scrap to the TextEdit scrap.
  6807. \ TEToScrap
  6808. 8
  6809. FUNCTION TEToScrap : OSErr;  [Not in ROM]
  6810.  
  6811.     TEToScrap copies the TextEdit scrap to the desk scrap.
  6812.  
  6813. (warning)
  6814.          You must call the Scrap Manager function ZeroScrap to
  6815.      initialize the desk scrap or clear its previous contents
  6816.      before calling TEToScrap.
  6817. \ TEScrapHandle
  6818. 8
  6819. FUNCTION TEScarapHandle : Handle;  [Not in ROM]
  6820.  
  6821.     TEScrapHandle returns a handle to the TExtEdit scrap.
  6822. \ TEGetScrapLen
  6823. 8
  6824. FUNCTION TEGetScrapLen : LONGINT; [Not in ROM]
  6825.  
  6826.     TEGetScrapLen returns the size of the TextEdit scrap in bytes.
  6827. \ TESetScrapLen
  6828. 8
  6829. PROCEDURE TESetScrapLen (length: LONGINT); [Not in ROM]
  6830.  
  6831.     TESetScrapLen sets the size of the TextEdit scrap to the given
  6832. number of bytes.
  6833. \ TECalText
  6834. 8
  6835. PROCEDURE TECalText (hTE: TEHandle);
  6836.  
  6837.     TECalText recalculates the beginnings of all lines of text in the
  6838. edit record specified by hTE, updating elements of the lineStarts array.
  6839. Call  TECalText if you've changed the destination rectangle, the hText
  6840. field, or any other field that affects the number of characters per line.
  6841.  
  6842. (note)
  6843.       There are two ways to specify text to be edited. The
  6844.       easiest method is to use TESetText, which takes an
  6845.       existing edit record, creates a copy of the specified
  6846.       text, and stores a handle to the copy in the edit record.
  6847.       You can instead directly change the hText field of the
  6848.       edit record, and then call TECalText to recalculate the
  6849.       lineStarts aray to match the new text. If you have a
  6850.       lot of text, you can use the latter method to save space.
  6851. \ TESelView
  6852. 8
  6853. PROCEDURE TESelView (hTE: TEHandle);
  6854.  
  6855.     If automatic scrolling has been enabled (by a call to TEAutoView,
  6856. described below), TESelView makes sure that the selection range is
  6857. visible, scrolling it into the view rectangle if necessary.
  6858. If automatic scrolling is disabled, TESelView does nothing.
  6859.  
  6860. Note:  The top left of the insertion is scrolled into view; if text
  6861. is being displayed in a rectangle that’s not tall enough, automatic
  6862. scrolling could cause the text to jump up and down at times.
  6863. \TEPinScroll
  6864. 8
  6865. PROCEDURE TEPinScroll (dh,dv: INTEGER; hTE: TEHandle);
  6866.  
  6867.     TEPinScroll is similar to TEScroll except that it stops scrolling
  6868. when the last line scrolls into the view rectangle.
  6869. \TEAutoView
  6870. 8
  6871. PROCEDURE TEAutoView (auto: BOOLEAN; hTE: TEHandle);
  6872.  
  6873.     TEAutoView enables and disables automatic scrolling of text in the
  6874. edit record specified by hTe. If the auto parameter is FALSE,
  6875. automatic scrolling is disabled and calling TESelView has no effect.
  6876. \ InitDialogs
  6877. 9
  6878. PROCEDURE InitDialogs (restartProc: ProcPtr);
  6879.  
  6880.     Call InitDialogs once before all other Dialog Manager routines, to
  6881. initialize the Dialog Manager.
  6882.  
  6883.   -It sets a pointer to a fail-safe procedure as specified by
  6884.    restartProc; this pointer will be accessed when a system error
  6885.    (such as running out of memory) occurs. RestartProc should point
  6886.    to a procedure that will restart the application after a system
  6887.    error. If no such procedure is desired, pass NIL as the parameter.
  6888.  
  6889.   -It installs the standard sound procedure.
  6890.  
  6891.   -It passes empty strings to ParamText.
  6892. \ ErrorSound
  6893. 9
  6894. PROCEDURE ErrorSound (soundProc: ProcPtr);
  6895.  
  6896.     ErrorSound sets the sound procedure for dialogs and alerts to the
  6897. procedure pointed to by soundProc; if you don't call ErrorSound, the
  6898. Dialog Manager uses the standard sound procedure. (For details, see
  6899. the "Alerts" section abouve.)  If you pass NIL for soundProc, there will
  6900. be no sound (or menu bar blinking) at all.
  6901. \ SetDAFont
  6902. 9
  6903. PROCEDURE SetDAFont (fontNum: INTEGER);  [Pascal only]
  6904.  
  6905.     For subsequently created dialogs and alerts, SetDAFont sets the font
  6906. of the dialog or alert window's grafPort to the font having the
  6907. specified font number. If you don't call this procedure, the system
  6908. font is used. SetDAFont affects statText and editText items but not
  6909. titles of controls, which are always in the system font.
  6910. \ NewDialog
  6911. 9
  6912. FUNCTION NewDialog (dStorage: Ptr; boundsRect: Rect; title: Str255;
  6913.             visible: BOOLEAN; procID: INTEGER; behind: WindowPtr;
  6914.         goAwayFlag: BOOLEAN; refCon: LongInt; items: Handle) :
  6915.         DialogPtr;
  6916.  
  6917.     NewDialog creates a dialog as specified by its parameters and
  6918. returns a pointer to the new dialog. The first eight parameters
  6919. (dStorage through refCon) are pased to the Window Manager function
  6920. NewWindow, which creates the dialog window; the meanings of these
  6921. parameters are summarized below. The items parameter is a handle to the
  6922. dialog's item list. You can get the items handle by calling the
  6923. Resource Mangager to read the item list from the resource file into
  6924. memory.
  6925.  
  6926. (note)
  6927.       Advanced programmers can create their own item lists in
  6928.       memory rather than have them read from a resource file.
  6929.       The exact format is given later under "Formats of
  6930.       Resources for Dialogs and Alerts".
  6931.  
  6932.     DStorage is analogous to the wStorage parameter of NewWindow; it's a
  6933. pointer to the storage to use for the dialog record. If you pass NIL
  6934. for dStorage, the dialog record will be allocated on the heap (which,
  6935. in the case of modeless dialogs, may cause the heap to become
  6936. fragmented).
  6937.  
  6938.     BoundsRect, a rectangle given in global coordinates, determines the
  6939. dialog window's size and location. It becomes the portRect of the
  6940. window's grafPort. Remember that the top coordinate of this rectangle
  6941. should be at least 25 points below the top of the screen for a modal
  6942. dialog, to allow for the menu bar and the border around the portRect,
  6943. and at least 40 points below the top of the screen for a modeless
  6944. dialog, to allow for the menu bar and the window's title bar.
  6945.  
  6946.     Title is the title of a modeless dialog box; pass the empty string
  6947. for modal dialogs.
  6948.  
  6949.     If the visible parameter is TRUE, the dialog window is drawn on the
  6950. screen. If it's FALSE, the window is initially invisible and may later
  6951. be shown with a call to the Window Manager procedure ShowWindow.
  6952.  
  6953. (note)
  6954.       NewDialog generates an update event for the entire window
  6955.       contents, so the items aren't drawn immediately, with the
  6956.       exception of controls. The Dialog Manager calls the
  6957.       Control Manager to draw controls, and the Control Manager
  6958.       draws them immediately rather than via the standard
  6959.       update mechanism. Because of this, the Dialog Manager
  6960.       calls the Window Manager procedure ValidRect for the
  6961.       enclosing rectangle of each control, so the controls
  6962.       won't be drawn twice. If you find that the other items
  6963.       aren't being drawn soon enough after the controls, try 
  6964.       making the window invisible initially and then calling
  6965.       ShowWindow to show it.
  6966.  
  6967.     ProcID is the window definition ID, which leads to the window
  6968. definition function for this type of window. The window definition IDs
  6969. for the standard types of dialog window are dBoxProc for the modal type
  6970. and documentProc for the modeless type.
  6971.  
  6972.     The behind parameter specifies the window behind which the dialog
  6973. window is to be placed on the desktop. Pass POINTER(-1) to bring up
  6974. the dialog window in front of all other windows.
  6975.  
  6976.     GoAwayFlag applies to modeles dialog boxes; if it's TRUE, the dialog
  6977. window has a close box in its title bar when the window is active.
  6978.  
  6979.     RefCon is the dialog window's reference value, which the application
  6980. may store into and access for any purpose.
  6981.  
  6982.     NewDialog sets the font of the dialog window's grafPort to the
  6983. system font or, if you previously called SetDAFont, to the specified
  6984. font. It also sets the window class in the window record to dialogKind.
  6985. \ GetNewDialog
  6986. 9
  6987. FUNCTION GetNewDialog (dialogID: INTEGER; dStorage: Ptr; behind:
  6988.             WindowPtr) : DialogPtr;
  6989.  
  6990.     Like NewDialog (above), GetNewDialog creates a dialog as specified
  6991. by its parameters and returns a pointer to the new dialog. Instead of
  6992. having the parameters boundsRect, title, visible, procID, goAwayFlag,
  6993. and refCon, GetNewDialog has a single dialogID parameter, where
  6994. dialogID is the resource ID of a dialog template that supplies the same
  6995. information as those parameters. The dialog template also contains the
  6996. resource ID of the dialog's item list. After calling the Resource
  6997. Manager to read the item list into memory (if it's not already in
  6998. memory), GetNewDialog makes a copy of the item list and uses that copy;
  6999. thus you may have multiple independent dialogs whose items have the
  7000. same types, locations, and initial contents. The dStorage and behind
  7001. parameters of GetNewDialog have the same meaning as in NewDialog.
  7002. \ CloseDialog
  7003. 9
  7004. PROCEDURE CloseDialog (theDialog: DialogPtr);
  7005.  
  7006.     CloseDialog removes theDialog's window from the screen and deletes
  7007. it from the window list, just as when the Window Manager procedure
  7008. CloseWindow is called. It releases the memory occupied by the
  7009. following:
  7010.  
  7011.   -The data structures associated with the dialog window (such as the
  7012.    window's structure, content, and update regions).
  7013.  
  7014.   -All the items in the dialog (except for pictures and icons, which
  7015.    might be shared resources), and any data structures associated
  7016.    with them. For example, it would dispose of the region occupied
  7017.    by the thumb of a scroll bar, or a similar region for some other
  7018.    control in the dialog.
  7019.  
  7020.     CloseDialog does not dispose of the dialog record or the item list.
  7021. Figure 6 illustrates the effect of CloseDialog (and DisposDialog,
  7022. described below).
  7023.  
  7024.     Call CloseDialog when you're done with a dialog if you supplied
  7025. NewDialog or GetNewDialog with a pointer to the dialog storage (in the
  7026. dStorage parameter) when you created the dialog.
  7027.  
  7028. (note)
  7029.       Even if you didn't supply a pointer to the dialog
  7030.       storage, you may want to call CloseDialog if you created
  7031.       the dialog with NewDialog. You would call CloseDialog if
  7032.       you wanted to keep the item list around (since, unlike
  7033.       GetNewDialog, NewDialog does not use a copy of the item
  7034.       list).
  7035. \ DisposDialog
  7036. 9
  7037. PROCEDURE DisposDialog (theDialog: DialogPtr);
  7038.  
  7039.     DisposDialog calls CloseDialog (above) and then releases the memory
  7040. occupied by the dialog's item list and dialog record. Call
  7041. DisposDialog when you're done with a dialog if you let the dialog
  7042. record be allocated on the heap when you created the dialog (by passing
  7043. NIL as the dStorage parameter to NewDialog or GetNewDialog).
  7044. \ CouldDialog
  7045. 9
  7046. PROCEDURE CouldDialog (dialogID:  INTEGER);
  7047.  
  7048.     CouldDialog ensures that the dialog template having the given
  7049. resource ID is in memory and makes it unable to be purged. It does the
  7050. same for the dialog window's definition function, the dialog's item list
  7051. resource, and any item defined as resources. This is useful if the
  7052. dialog box may come up when the resource file isn't accessible, such as
  7053. during a disk copy.
  7054. \ FreeDialog
  7055. 9
  7056. PROCEDURE FreeDialog (dialogID: INTEGER);
  7057.  
  7058.     Given the resource ID of a dialog template previously specified in a
  7059. call to CouldDialog (above), FreeDialog undoes the effect of
  7060. CouldDialog. It should be called when there's no longer a need to keep
  7061. the resources in memory.
  7062. \ ModalDialog
  7063. 9
  7064. PROCEDURE ModalDialog (filterProc: ProcPtr; VAR itemHit: INTEGER);
  7065.  
  7066.     Call ModalDialog after creating a modal dialog and bringing up its
  7067. window in the frontmost plane. ModalDialog repeatedly gets and handles
  7068. events in the dialog's window; after handling an event involving an
  7069. enabled dialog item, it returns with the item number in itemHit.
  7070. Normally you'll then do whatever is appropriate as a response to an 
  7071. event in that item.
  7072.  
  7073.     ModalDialog gets each event by calling the Toolbox Event Manager
  7074. function GetNextEvent. If the event is a mouse-down event outside the
  7075. content region of the dialog window, ModalDialog emits sound number 1
  7076. (which should be a single beep) and gets the next event; otherwise, it
  7077. filters and handles the event as described below.
  7078.  
  7079. (note)
  7080.       Once before getting each event, ModalDialog calls
  7081.       SystemTask, a Desk Manager procedure that needs to be
  7082.       called regularly if the application is to support the use
  7083.       of desk accessories.
  7084.  
  7085.     The filterProc parameter determines how events are filtered. If it's
  7086.  NIL, the standard filterProc function is executed; this causes
  7087.  ModalDialog to return 1 in itemHit if the Return key or Enter key is
  7088.  pressed. If filterProc isn't NIL, ModalDialog filters events by
  7089.  executing the function it points to. Your filterProc function should
  7090.  have three parameters and return a Boolean value. For example, this is
  7091.  how it would be declared if it were named MyFilter:
  7092.  
  7093.       FUNCTION MyFilter (theDialog: DialogPtr; VAR theEvent:
  7094.                          EventRecord; VAR itemHit: INTEGER ) : BOOLEAN;
  7095.  
  7096.     A function result of FALSE tells ModalDialog to go ahead and handle
  7097. the event, which either can be sent through unchanged or can be changed
  7098. to simulate a different event. A function result of TRUE tells
  7099. ModalDialog to return imediately rather than handle the event; in this
  7100. case, the filterProc function sets itemHit to the item number that
  7101. ModalDialog should return.
  7102.  
  7103. (note)
  7104.       ModalDialog calls GetNextEvent with a mask that excludes
  7105.       disk-inserted events. To receive disk-inserted events,
  7106.       your filterProc function can call GetNextEvent (or
  7107.       EventAvail) with a mask that accepts only that type of event.
  7108.  
  7109.     ModalDialog handles the evnets for which the filterProc function
  7110. returns FALSE as follows:
  7111.  
  7112.   -In response to an activate or update event for the dialog window,
  7113.    ModalDialog activates or updates the window.
  7114.  
  7115.   -If the mouse button is pressed in an editText item, ModalDialog
  7116.    responds to the mouse activity as appropriate (displaying an
  7117.    insertion point or selecting text). If a key-down event occurs
  7118.    and there's an editText item, text entry and editing are handled
  7119.    in the standard way for such items (except that if the Command key
  7120.    is down, ModalDialog responds as though it isn't). In either
  7121.    case, ModalDialog returns if the editText item is enabled or does
  7122.    nothing if it's disabled. If a key-down event occurs when there's
  7123.    no editText item, ModalDialog does nothing.
  7124.  
  7125.   -If the mouse button is pressed in a control, ModalDialog calls the
  7126.    Control Manager function TrackControl. If the mouse button is
  7127.    released inside the control and the control is enabled,
  7128.    ModalDialog returns; otherwise, it does nothing.
  7129.  
  7130.   -If the mouse button is pressed in any other enabled item in the
  7131.    dialog box, ModalDialog returns. If the mouse button is pressed
  7132.    in any other disabled item or in no item, or if any other event
  7133.    occurs, ModalDialog does nothing.
  7134. \ IsDialogEvent
  7135. 9
  7136. FUNCTION IsDialogEvent (theEvent: EventRecord) : BOOLEAN;
  7137.  
  7138.     If your application includes any modeless dialogs, call
  7139. IsDialogEvent after calling the Toolbox Event Manager function
  7140. GetNextEvent. Pass the current event in theEvent. IsDialogEvent
  7141. determines whether theEvent needs to be handled as part of a dialog. If
  7142. theEvent is an activate or update event for a dialog window, a
  7143. mouse-down event in the content region of an active dialog window, or
  7144. any other type of event when a dialog window is active, IsDialogEvent
  7145. returns TRUE; otherwise, it returns FALSE.
  7146.  
  7147.     When FALSE is returned, just handle the event yourself like any
  7148. other event that's not dialog-related. When TRUE is returned, you'll
  7149. generally end up passing the event to DialogSelect for it to handle (as
  7150. described below), but first you should do some additional checking:
  7151.  
  7152.    - DialogSelect doesn't handle keyboard equivalents for commands.
  7153.      Check whether the event is a key-down event with the Command key
  7154.      held down and, if so, carry out the command if it's one that
  7155.      applies when a dialog window is active. (If the command doesn't
  7156.      so apply, do nothing.)
  7157.  
  7158.   - In special cases, you may want to bypass DialogSelect or do some
  7159.     preprocessing before calling it. If so, check for those events
  7160.     and respond accordingly. You would need to do this, for example,
  7161.     if the dialog is to respond to disk-inserted events.
  7162.  
  7163.     For cases other than these, pass the event to DialogSelect for it to
  7164. handle.
  7165. \ DialogSelect
  7166. 9
  7167. FUNCTION DialogSelect (theEvent: EventRecord; VAR theDialog: DialogPtr;
  7168.             VAR itemHit: INTEGER) : BOOLEAN;
  7169.  
  7170.     You'll normally call DialogSelect after IsDialogEvent, passing in
  7171. theEvent an event that needs to be handled as part of a modeless
  7172. dialog. DialogSelect handles the event as described below. If the
  7173. event involves an enabled dialog item, DialogSelect returns a function
  7174. result of TRUE with the dialog pointer in theDialog and the item number
  7175. in itemHit; otherwise, it returns FALSE with theeDialog and itemHit
  7176. undefined. Normally when DialogSelect returns TRUE, you'll do whatever
  7177. is appropriate as a response to the event, and when it returns FALSE
  7178. you'll do nothing.
  7179.  
  7180.     If the event is an activate or update event for a dialog window,
  7181. DialogSelect activates or updates the window ane returns FALSE.
  7182.  
  7183.     If the event is a mouse-down event in an editText item, DialogSelect
  7184. responds as appropriate (displaying an insertion point or selecting
  7185. text). If it's a key-down event and there's an editText item, text
  7186. entry and editing are handled in the standard way. In either case,
  7187. DialogSelect returns TRUE if the editText item is enabled or FALSE if
  7188. it's disabled. If a key-down event is passed when there's no editText
  7189. item, DialogSelect returns FALSE.
  7190.  
  7191. (note)
  7192.       For a key-down event, DialogSelect doesn't check to see
  7193.       whether the Command key is held down; to handle keyboard
  7194.       equivalents of commands, you have to check for them
  7195.       before calling DialogSelect. Similarly, to treat a typed
  7196.       character in a special way (such as ignore it, or make it
  7197.       have the same effect as another character or as clicking
  7198.       a button), you need to check for a key-down event with
  7199.       that character before calling DialogSelect.
  7200.  
  7201.     If the event is a mouse-down event in a control, DialogSelect calls
  7202. the Control Manager function TrackControl. If the mouse button is
  7203. released inside the control and the control is enabled, DialogSelect
  7204. returns TRUE; otherwise, it returns FALSE.
  7205.  
  7206.     If the event is a mouse-down event in any other enabled item,
  7207. DialogSelect returns TRUE. If it's  a mouse-down event in any other
  7208. disabled item or in no item, or if it's any other event, DialogSelect
  7209. returns FALSE.
  7210. \ DlgCut
  7211. 9
  7212. PROCEDURE DlgCut (theDialog: DialogPtr);   [Pascal only]
  7213.  
  7214.     DlgCut checks whether theDialog has any editText items and, if so,
  7215. applies the textEdit procedure TECut to the currently selected editText
  7216. item. (If the dialog record's editField is 0 or greater, DlgCut passes
  7217. the contents of the textH field to TECut.)  You can call DlgCut to
  7218. handle the editing command Cut when a modeless dialog window is active.
  7219. \ DlgCopy
  7220. 9
  7221. PROCEDURE DlgCopy (theDialog: DialogPtr);   [Pascal only]
  7222.  
  7223.     DlgCopy is the same as DlgCut (above) except that it calls TECopy,
  7224. for handling the Copy command.
  7225. \ DlgPaste
  7226. 9
  7227. PROCEDURE DlgPaste (theDialog: DialogPtr);   [Pascal only]
  7228.  
  7229.     DlgPaste is the same as DlgCut (above) except that it calls TEPaste,
  7230. for handling the Paste command.
  7231. \ DlgDelete
  7232. 9
  7233. PROCEDURE DlgDelete (theDialog: DialogPtr);   [Pascal only]
  7234.  
  7235.     DlgDelete is the same as DlgCut (above) except that it calls
  7236. TEDelete, for handling the Clear command.
  7237. \ DrawDialog
  7238. 9
  7239. PROCEDURE DrawDialog (theDialog: DialogPtr);
  7240.  
  7241.     DrawDialog draws the contents of the given dialog box. Since
  7242. DialogSelect and ModallDialog handle dialog window updating, this
  7243. procedure is useful only in unusual situations. You would call it, for
  7244. example, to display a dialog box that doesn't require any response but
  7245. merely tells the user what's going on during a time-consuming process.
  7246. \ Alert
  7247. 9
  7248. FUNCTION Alert (alertID: INTEGER; filterProc: ProcPtr) : INTEGER;
  7249.  
  7250.     This function invokes the alert defined by the alert template that
  7251. has the given resource ID. It calls the currnet sound procedure, if
  7252. any,l passing it the sound number specified in the alert template for
  7253. this stage of the alert. If no alert box is to be drawn at this stage,
  7254. Alert returns a function result of -1; otherwise, it creates and
  7255. displays the alert window for this alert and draws the alert box.
  7256.  
  7257. (note)
  7258.       It creates the alert window by calling NewDialog, and
  7259.       does the rest of its processing by calling ModalDialog.
  7260.  
  7261.     Alert repeatedly gets and handles events in the alert window until
  7262. an enabled item is clicked, at which time it returns the item number.
  7263. Normally you'll then do whatever is appropriate in response to a click
  7264. of that item.
  7265.  
  7266.     Alert gets each event by calling theToolbox Event Manager function
  7267. GetNextEvent. If the event is a mouse-down event outside the content
  7268. region of the alert window, Alert emits sound number 1 (which should be
  7269. a single beep) and gets the next event; otherwise, it filters and
  7270. handles the event as describe below.
  7271.  
  7272.     The filterProc parameter has the same meaning as in ModalDialog (see
  7273. above). If it's NIL, the standard filterProc function is executed,
  7274. which makes the Return key or the Enter key have the same effect as
  7275. clicking the default button. If you specify your own filterProc
  7276. function and want to retain this feature, you must include it in your
  7277. function. You can find out what the current default button is by
  7278. looking at the aDefItem field of the dialog record for the alert (via
  7279. the dialog pointer passed to the function).
  7280.  
  7281.     Alert handles the events for which the filterProc function returns
  7282. FALSE as follows:
  7283.  
  7284.  
  7285.   - If the mouse button is pressed in a control, Alert calls the
  7286.     Control Manager procedure TrackControl. If the mouse buton is
  7287.     released inside the control and the control is enabled, Alert
  7288.     returns; otherwise, it does nothing.
  7289.  
  7290.   - If the mouse button is pressed in any other enabled item, Alert
  7291.     simply returns. If it's pressed in any other disabled item or in 
  7292.     no item, or if any other event occurs, Alert does nothing.
  7293.  
  7294.     Before returning to the application with the item number, Alert
  7295. removes the alert box from the screen. (It disposes of the alert window
  7296. and its associated data structures, the item list, and the items.)
  7297.  
  7298. (note)
  7299.        The Alert function's removal of the alert box would not
  7300.        be the desired result if the user clicked a check box or
  7301.        radio button; however, normally alerts contain only
  7302.        static text, icons, pictures, and buttons that are
  7303.        supposed to make the alert box go away. If your alert
  7304.        contains other items besides these, consider whether it
  7305.        might be more appropriate as a dialog.
  7306. \ StopAlert
  7307. 9
  7308. FUNCTION StopAlert (alertID: INTEGER; filterProc: ProcPtr) : INTEGER;
  7309.  
  7310.     StopAlert is the same as the Alert function (above) except that
  7311. before drawing the items of the alert in the alert box, it draws the
  7312. Stop icon in the top left corner of the box (within the rectangle
  7313. (10,20,42,52)). The Stop icon has the following resource ID:
  7314.  
  7315.        CONST stopIcon = 0;
  7316.  
  7317.     If the application's resource file doesn't include an icon with that
  7318. ID number, the Dialog Manager uses the standart Stop icon in the system
  7319. resource file (see Figure 7).
  7320. \ NoteAlert
  7321. 9
  7322. FUNCTION NoteAlert (alertID: INTEGER; filterProcf: ProcPtr) : INTEGER;
  7323.  
  7324.     NoteAlert is like StopAlert except that it draws the Note icon,
  7325. which has the following resource ID:
  7326.  
  7327.        CONST noteIcon = 1;
  7328. \ CautionAlert
  7329. 9
  7330. FUNCTION CautionAlert (alertID: INTEGER; filterProc: ProcPtr) :
  7331.            INTEGER;
  7332.  
  7333.     CautionAlert is like StopAlert except that it draws the Caution
  7334. icon, which has the following resource ID:
  7335.  
  7336.        CONST ctnIcon = 2;
  7337. \ CouldAlert
  7338. 9
  7339. PROCEDURE CouldAlert (alertID: INTEGER);
  7340.  
  7341.     CouldAlert ensures that the alert template having the given resource
  7342. ID is in memory and makes it unable to be purged. It does the same for
  7343. the alert window's definition function, the alert's item list resource,
  7344. and any items defined as resources. This is useful if the alert may
  7345. occur when the resource file isn't accessible, such as during a disk
  7346. copy.
  7347. \ FreeAlert
  7348. 9
  7349. PROCEDURE FreeAlert (alertID: INTEGER);
  7350.  
  7351.     Given the resource ID of an alert template previously specified in a
  7352. call to CouldAlert (above), FreeAlert undoes the effect of CouldAlert.
  7353. It should be called when there's no longer a need to keep the resources
  7354. in memory.
  7355. \ ParamText
  7356. 9
  7357. PROCEDURE ParamText (param0,param1,param2,param3: Str255);
  7358.  
  7359.     ParamText provides a means of substituting text in statText items:
  7360. param0 through param3 will replace the special strings '^0' through
  7361. '^I3' in all statText items in all subsequent dialog or alert boxes.
  7362. Pass empty strings for parameters not used.
  7363.  
  7364.     For example, if the text is defined as 'Cannot open document ^0' and
  7365. docName is a string variable containg a document name that the user
  7366. typed, you can call ParamText(docName, '','','').
  7367.  
  7368. (warning)
  7369.          All strings that will need to be translated to foreign
  7370.         languages should be stored in resource files.
  7371.  
  7372.  
  7373.  
  7374. \ GetDItem
  7375. 9
  7376. PROCEDURE GetDItem (theDialog: DialogPtr; itemNo: INTEGER; VAR type:
  7377.                     INTEGER; VAR item: Handle; VAR box: Rect);
  7378.  
  7379.     GetDItem returns in its VAR parameters the following information
  7380. about the item numbered itemNo in the given dialog's item list: in the
  7381. type parameter, the item type; in the item parameter, a handle to the
  7382. item (or, for item type userItem, the procedure pointer); and in the box
  7383. parameter, the display rectangle for the item.
  7384.  
  7385.     Suppose, for example, that you want to change the title of a control
  7386. in a dialog box. You can get the item handle with GetDItem, convert it
  7387. to type ControlHandle, and call the Control Manager procedure SetCTitle
  7388. to change the title. Similarly, to move the control or change its size,
  7389. you would call MoveControl or SizeControl.
  7390.  
  7391. (note)
  7392.       To access the text of a statText or editText item, pass
  7393.       the handle returned by GetDItem to GetIText or SetIText
  7394.       (see below).
  7395. \ SetDItem
  7396. 9
  7397. PROCEDURE SetDItem (theDialog: DialogPtr; itemNo: INTEGER; type:
  7398.             INTEGER; item: Handle; box: rect);
  7399.  
  7400.     SetDItem sets the item numbered itemNo in the given dialog's item
  7401. list, as specified by the parameters (without drawing the item). The
  7402. type parameter is the item type; the item parameter is a handle to the
  7403. item (or, for item type userItem, the procedure pointer); and the box
  7404. parameter is the display rectangle for the item.
  7405.  
  7406.     Consider, for example, how to install an item of type userItem in a
  7407. dialog:  In the item list in the resource file, define an item in which
  7408. the type is set to userItem and the display rectangle to (0,0,0,0).
  7409. Specify that the dialog window be invisible (in either the dialog
  7410. template or the NewDialog call). After creating the dialog, convert
  7411. the item's procedure pointer to type Handle; then call SetDItem,
  7412. passing that handle and the display rectangle for the item. Finally,
  7413. call the Window Manager procedure ShowWindow to display the dialog
  7414. window.
  7415.  
  7416. (note)
  7417.       Do not use SetDItem to change the text of a statText or
  7418.       editText item or to change or move a control. See the
  7419.       description of GetDItem above for more information.
  7420. \ GetIText
  7421. 9
  7422. PROCEDURE GetIText (item: Handle; VAR text: str255);
  7423.  
  7424.     Given a handle to a statText or editText item in a dialog box, as
  7425. returned by GetDItem, GetIText returns the text of the item in the text
  7426. parameter.
  7427. \ SetIText
  7428. 9
  7429. PROCEDURE SetIText (item: Handle; text: Str255);
  7430.  
  7431.     Given a handle to a statText or editText item in a dialog box, as
  7432. returned by GetDItem, SetIText sets the text of the item to the
  7433. specified text and draws the item. For example, suppose the exact
  7434. content of a dialog's text item cannot be determined until the
  7435. application is running, but the display rectangle is defined in the
  7436. resource file:  Call GetDItem to get a handle to the item, and call
  7437. SetIText with the desired text.
  7438. \ SelIText
  7439. 9
  7440. PROCEDURE SelIText (theDialog: DIalogPtr; itemNo: INTEGER;
  7441.            strtSel,endSel: INTEGER);
  7442.  
  7443.     Given a pointer to a dialog and the item number of an editText item
  7444. in the dialog box, SelIText does the following:
  7445.  
  7446.    - If the item contains text, SelIText sets the selection range to
  7447.      extend from character position strtSel up to but not including
  7448.      character position endSel. The selection range is inverted unless
  7449.      strtSel equals endSel, in which case a blinking vertical bar is
  7450.      displayed to indicate an insertion point at that position.
  7451.  
  7452.    - If the item doesn't contain text, SelIText simply displays the
  7453.      insertion point.
  7454.  
  7455.     For example, if the user makes an unacceptable entry in the editText
  7456. item, the application can put up an alert box reporting the problem and
  7457. then select the entire text of the item so it can be replaced by a new
  7458. entry. (Without this procedure, the user would have to select the item
  7459. before making the new entry.)
  7460.  
  7461. (note)
  7462.       You can select the entire text by specifying 0 for
  7463.       strtSel and a very large number for endSel. For details
  7464.       about selection range and character position, see the
  7465.       TextEdit manual.
  7466. \ GetAlrtStage
  7467. 9
  7468. FUNCTION GetAlrtStage : INTEGER;   [Pascal only]
  7469.  
  7470.     GetAlrtStage returns the stage of the last occurrence of an alert,
  7471. as a number from 0 to 3.
  7472. 9
  7473. PROCEDURE ResetAlrtStage;   [Pascal only]
  7474.  
  7475.     ResetAlrtStage resets the stage of the last occurrence of an alert
  7476. so that the next occurrenct of the same alert will be treatd as its
  7477. first stage. This is useful, for example, when you've used ParamText
  7478. to change the text of an alert such that from the user's point of view
  7479. it's a different alert.
  7480. \ HideDItem
  7481. 9
  7482. PROCEDURE HideDItem (theDialog: DialogPtr; itemNo: INTEGER);
  7483.  
  7484.     HideDItem hides the item numbered itemNo in the given dialog’s item
  7485. list by giving the item a display rectangle that’s off the screen.
  7486. (Specifically, if the left coordinate of the item’s display rectangle
  7487. is less than 8192, ShowDItem adds 16384 to both the left and right
  7488. coordinates the rectangle.)  If the item is already hidden (that is,
  7489. if the left coordinate is greater than 8192), HideDItem does nothing.
  7490.  
  7491.     HideDItem calls the EraseRect procedure on the item’s enclosing
  7492. rectangle and adds the rectangle that contained the item (not
  7493. necessarily the item’s display rectangle) to the update region.
  7494. If the specified item is an active editText item, the item is first
  7495. deactivated (by calling TEDeactivate).
  7496.  
  7497. Note:  If you have items that are close to each other, be aware that
  7498.        the Dialog Manager draws outside of the enclosing rectangle by 3
  7499.        pixels for editText items and by 4 pixels for a default button.
  7500.  
  7501.     An item that’s been hidden by HideDItem can be redisplayed by the
  7502. ShowDItem procedure.
  7503.  
  7504. Note:  To create a hidden item in a dialog item list, simply add
  7505.        16384 to the left and right coordinates of the display rectangle.
  7506. \ ShowDItem
  7507. 9
  7508. PROCEDURE ShowDItem (theDialog: DialogPtr; itemNo: INTEGER);
  7509.  
  7510.     ShowDItem redisplays the item numbered itemNo, previously hidden by
  7511. HideDItem, by giving the item the display rectangle it had prior to
  7512. the HideDItem call. (Specifically, if the left coordinate of the
  7513. item’s display rectangle is greater than 8192, ShowDItem subtracts
  7514. 16384 from both the left and right coordinates the rectangle.)
  7515. If the item is already visible (that is, if the left coordinate is
  7516. less than 8192), ShowDItem does nothing.
  7517.  
  7518.     ShowDItem adds the rectangle that contained the item (not
  7519. necessarily the item’s display rectangle) to the update region so
  7520. that it will be drawn. If the item becomes the only editText item,
  7521. ShowDItem activates it (by calling TEActivate).
  7522. \FindDItem
  7523. 9
  7524. FUNCTION FindDItem (theDialog: DialogPtr; thePt: Point) : INTEGER;
  7525.  
  7526.     FindDItem returns the item number of the item containing the point
  7527. specified, in local coordinates, by thePt. If the point doesn’t lie
  7528. within the item’s rectangle, FindDItem returns –1.  If there are
  7529. overlapping items, it returns the item number of the first item in
  7530. the list containing the point. FindDItem is useful for changing the
  7531. cursor when it’s over a particular item.
  7532.  
  7533. Note:  FindDItem will return the item number of disabled items as well.
  7534. \UpdtDialog
  7535. 9
  7536. PROCEDURE UpdtDialog (theDialog: DialogPtr; updateRgn: RgnHandle);
  7537.  
  7538.     UpdtDialog is a faster version of the DrawDialog procedure.
  7539. Instead of drawing the entire contents of the given dialog box,
  7540. UpdtDialog draws only the items that are in a specified update region.
  7541. UpdtDialog is called in response to an update event, and is usually
  7542. bracketed by calls to the Window Manager procedures BeginUpdate and
  7543. EndUpdate. UpdateRgn should be set to the visRgn of theWindow’s port.
  7544. (For more details, see the BeginUpdate procedure in chapter 9 of
  7545. Volume I.)
  7546. \ OpenDeskAcc
  7547. 10
  7548. FUNCTION OpenDeskAcc (theAcc: Str255) : INTEGER;
  7549.  
  7550.     OpenDeskAcc opens the desk accessory having the given name and
  7551. displays its window (if any) as the active window. The name is the
  7552. accessory's resource name, which you get from the Apple menu by calling
  7553. the Menu Manager procedure GetItem. OpenDeskAcc calls the Resource
  7554. Manager to read the desk accessory from the resource file.
  7555.  
  7556.     You should ignore the value returned by OpenDeskAcc. If the desk
  7557. accessory is successfully opened, the function result is its driver
  7558. reference number; as described under CloseDeskAcc below, you don't need
  7559. this number to close the accessory. If the desk accessory can't be
  7560. opened, the function result is undefined; the accessory will have taken
  7561. care of informing the user of the problem (such as memory full) and not
  7562. displaying itself.
  7563.  
  7564. (warning)
  7565.          It may occasionally happen that the current grafPort will
  7566.          be the desk accessory's port upon return from
  7567.          OpenDeskAcc. To be safe, you should bracket your call to
  7568.          OpenDeskAcc with calls to the QuickDraw procedures
  7569.          GetPort and SetPort, to save and restore the current
  7570.          port.
  7571.  
  7572.     Before you open a desk accessory it's a good idea to determine
  7573. whether there's enough memory available. Here's an example of how to do
  7574. that:
  7575.  
  7576.         SetResLoad(FALSE);
  7577.         myResHandle := GetNamedResource('DRVR', theAcc);
  7578.         size := SizeResource(myResHandle);
  7579.         myHandle := NewHanddle(size + 3072);
  7580.         IF myHandle = NIL
  7581.           THEN {put up an alert indicating there's not enough memory}
  7582.           ELSE OpenDeskAcc(theAcc)
  7583.  
  7584.     The extra 3K bytes in the argument to the Memory Manager's NewHandle
  7585. function is an average amount of heap space used by desk accessories
  7586. while they're running.
  7587. \ CloseDeskAcc
  7588. 10
  7589. PROCEDURE CloseDeskAcc (refNum: INTEGER);
  7590.  
  7591.     When a system window is active and the user choses Close from the
  7592. File menu, call CloseDeskAcc to close the desk accessory. RefNum is the
  7593. driver reference number for the desk accessory, which you get from the
  7594. windowKind field of its window.
  7595.  
  7596.     The Desk Manager automatically closes a desk accessory if the user
  7597. clicks its close box. Also, since the application heap is released
  7598. when the application terminates, every desk accessory goes away at that
  7599. time.
  7600. \ SystemClick
  7601. 10
  7602. PROCEDURE SystemClick (theEvent: EventRecord; theWindow: WindowPtr);
  7603.  
  7604.     When a mouse-down event occurs and the Window Manager function
  7605. FindWindow reports that the mouse button was pressed in a system
  7606. window, the application should call SystemClick with the event record
  7607. and the window pointer. If the given window belongs to a desk
  7608. accessory, SystemClick sees that the event gets handled properly.
  7609.  
  7610.     SystemClick determines which part of the desk accessory's window the
  7611. mouse button was pressed in, and responds accordingly (similar to the
  7612. way your application responds to mouse activities in its own windows).
  7613.  
  7614.   - If the mouse button was pressed in the content region and the
  7615.     window and the window was active, SystemClick sends the mouse-down
  7616.     event to the desk accessory, which proceses it as appropriate.
  7617.  
  7618.   - If the mouse button was pressed in the content region and the
  7619.     window was inactive, SystemClick makes it the active window.
  7620.  
  7621.   - If the mouse button was pressed in the drag region, SystemClick
  7622.     calls the Window Manager procedure DragWindow to pull an outline
  7623.     of the window across the screen and move the window to a new
  7624.     location. If the window was inactive, DragWindow also makes it
  7625.     the active window (unless the Command key was pressed along with
  7626.     the mouse button).
  7627.  
  7628.   - If the mouse button was pressed in the go-away region, SystemClick
  7629.     calls the Window Manager function TrackGoAway to determine whether
  7630.     the mouse is still inside the go-away region when the click is
  7631.     completed:  if so, it tells the desk accessory to close itself
  7632.     otherwise, it does nothing.
  7633. \ SystemEdit
  7634. 10
  7635. FUNCTION SystemEdit (editCmd: INTEGER) : BOOLEAN;
  7636.  
  7637.     Call SystemEdit when there's a mouse-down event in the menu bar and
  7638. the user choses one of the five standard editing commands from the Edit
  7639. menu. Pass one of the following as the value of the editCmd parameter:
  7640.  
  7641.        EditCmd          Editing command
  7642.        0                Undo
  7643.        2                Cut
  7644.        3                Copy
  7645.        4                Paste
  7646.        5                Clear
  7647.  
  7648.  
  7649.     If your Edit menu contains these five commands in the standard
  7650. arrangement (the order listed above, with a gray line separating Undo
  7651. and Cut), you can simply call
  7652.  
  7653.      SystemEdit(menuItem - 1)
  7654.  
  7655.     If the active window dewsn't belong to a desk accessory, SystemEdit
  7656. returns FALSE; the application should then process the editing comand
  7657. as usual. If the active window dews belong to a desk accessory,
  7658. SystemEdit asks that accessory to process the command and returns TRUE;
  7659. in this case, the application should ignore the command.
  7660.  
  7661. (note)
  7662.       It's up to the application to make sure desk accessories 
  7663.       get their editing comands that are chosen from the Edit
  7664.       menu. In particular, make sure your application hasn't
  7665.       disabled the Edit menu or any of the five standard
  7666.       commands when a desk accessory is activated.
  7667. \ SystemTask
  7668. 10
  7669. PROCEDURE SystemTask;
  7670.  
  7671.     For each open desk accessory, SystemTask causes the accessory to
  7672. perform the periodic action defined for it, if any such action has been
  7673. defined and if the proper time period has passed since the action was
  7674. last performed. For example, a clock accessory can be deifined such
  7675. that the second hand is to move once every second; the periodic action
  7676. for the accessory will be to move the second hand to the next position,
  7677. and SystemTask will alert the accessory every second to perform that
  7678. action.
  7679.  
  7680.     You should call SystemTask as often as possible, usually once every
  7681. time through your main event loop. Call it more than once if your
  7682. applicaition dies an unusually large amount of processing each time
  7683. through the loopk.
  7684.  
  7685. (note)
  7686.       SystemTask should be called at least every sixtieth of a
  7687.       second.
  7688.  
  7689.  
  7690.  
  7691. \ SystemEvent
  7692. 10
  7693. FUNCTION SystemEvent (theEvent: EventRecord) : BOOLEAN;
  7694.  
  7695.     SystemEvent is called only by the Toolbox Event Manager function
  7696. GetNextEvent when it receives an event, to determine whether the event
  7697. should be handled by the application or by the system. If the given
  7698. event should be handled by the application, SystemEvent returns FALSE;
  7699. otherwise, it calls the appropriate system code to handle the event and
  7700. returns TRUE.
  7701.  
  7702.     In the case of a null, abort, or mouse-down event, SystemEvent does
  7703. nothing but return FALSE. Notice that it responds this way to a mouse-
  7704. down event even though the event may in fact have occurred in a system
  7705. window (and therefore may have to be handled by the system). The
  7706. reason for this is that the check for exactly where the event occurred
  7707. (via the Window Manager function FindWindow) is made later by the
  7708. applicaiton and so would be made twice if SystemEvent were also to do
  7709. it. To avoid this duplication, SystemEvent passes the event on to the
  7710. application and lets it make the sole call to FindWindow. Should
  7711. FindWindow reveal that the mouse-down event did occur in a system
  7712. window, the application can then call SystemClick, as described above,
  7713. to get the system to handle it.
  7714.  
  7715.     If the given event is a mouse-up or keyboard event, SystemEvent
  7716. checks whether the active window belongs to a desk accessory and whether
  7717. that accessory can handle this type of event. If so, it sends the event
  7718. to the desk accessory and returns TRUE; otherwise, it returns FALSE.
  7719.  
  7720. (note)
  7721.       It's unlikely that a desk accessory would not be set up
  7722.       to handle activate and update events.
  7723.  
  7724.     Finally, if the given event is a disk-inserted event, SylstemEvent
  7725. does some low-level processing (by calling the File Manager function
  7726. McountVol) but passes the event on to the application by returning
  7727. FALSE, in case the application wants to do further processing.
  7728. \ SystemMenu
  7729. 10
  7730. PROCEDURE SystemMenu (menuResult: LONGINT);
  7731.  
  7732.     SystemMenu is called only by the Menu Manager functions MenuSelect
  7733. and MenuKey, when an item in a menu belonging to a desk accessory has
  7734. been chosen. The menuResult parameter has the same format as the value
  7735. returned by MenuSelect and MenuKey:  the menu ID in the high-order word
  7736. and the menu item number in the low-order word. (The menu ID will be
  7737. negative.)  SystemMenu directs the desk accessory to perform the
  7738. appropriate action for the given menu item.
  7739. \ InfoScrap
  7740. 11
  7741. FUNCTION InfoScrap : PScrapStuff;
  7742.  
  7743.     dInfoScrap returns a pointer to information about the desk scrap.
  7744. The PScrapStuff data type is defined as follows:
  7745.  
  7746. TYPE PScrapStuff = ^ScrapStuff;
  7747.      ScrapStuff = RECORD
  7748.             scrapSize:    LONGINT;   {size of desk scrap}
  7749.             scrapHandle:  Handle;    {handle to desk scrap}
  7750.             scrapCount:   INTEGER;   {count changed by ZeroScrap}
  7751.             scratState:   INTEGER;   {tells where desk scrap is}
  7752.             scrapName:    StringPtr  {scrap file name}
  7753.           END;
  7754.  
  7755.  
  7756.     ScrapSize is the size of the desk scrap in bytes. ScrapHandle is a
  7757. handle to the scrap if it's in memory, or NIL if not.
  7758.  
  7759.     ScrapCount is a count that changes every time ZeroScrap is called,
  7760. and is useful for testing whether the contents of the desk scrap have
  7761. changed during the use of a desk accessory. ScrapState is positive if
  7762. the desk scrap is in memory, 0 if it's on the disk, or negative if it
  7763. hasn't been initialized by ZeroScrap.
  7764.  
  7765. (note)
  7766.        ScrapState is actually 0 if the scrap should be on the
  7767.        disk; for instance, if the user deletes the Clipboard
  7768.        file and then cuts something, the scrap is really in
  7769.        memory, but ScrapState will be 0.
  7770.  
  7771.  
  7772.     ScrapName is a pointer to the name of the scrap file, usually
  7773. "Clipboard File".
  7774.  
  7775. (note)
  7776.       InfoScrap assumes that the scrap file has a version
  7777.       number of 0 and is on the default volume. (Version
  7778.       numbers and volumes are described in the File Manager
  7779.       manual.)
  7780. \ UnloadScrap
  7781. 11
  7782. FUNCTION UnloadScrap : LONGINT;
  7783.  
  7784.     UnloadScrap writes the desk scrap from memory to the scrap file, and
  7785. relaeses the memory it occupied. If the desk scrap is already on the
  7786. disk, UnloadScrap does nothing. If no error occurs, UnloadScrap
  7787. returns the result code noErr; otherwise, it returns and Operating
  7788. System result code indicating an error.
  7789. \ LoadScrap
  7790. 11
  7791. FUNCTION LoadScrap : LONGINT;
  7792.  
  7793.     LoadScrap reads the desk scrap from the scrap file into memory. If
  7794. the desk scrap is already in memory, it does nothing. If no error
  7795. occurs, LoadScrap returns the result code noErr; otherwise, it returns
  7796. an Operating System result code indicating an error.
  7797. \ GetScrap
  7798. 11
  7799. FUNCTION GetScrap (hDest: Handle; theType: ResType; VAR offset:
  7800.                     LONGINT) : LONGINT;
  7801.  
  7802.     Given an existing handle in hDest, GetScrap reads the data of type
  7803. theType from the desk scrap (whether in memory or on the disk), makes a
  7804. copy of it in memory, and sets hDest to be a handle to the copy.
  7805. Usually you'll pass in hDest a handle to a minimum-size block; GetScrap
  7806. will resize the block and copy the scrap into it. If you pass NIL in
  7807. hDest, GetScrap will not read in the data. This is usefull if you want
  7808. to be sure the data is there before allocating space for its handle, or
  7809. if you just want to know the size of the data.
  7810.  
  7811.     In the offset parameter, GetScrap returns the location of the data
  7812. as an offset (in bytes) from the beginning of the desk scrap. If no
  7813. error occurs, the function result is the length of the data in bytes;
  7814. otherwise, it's either an appropriate Operatiing System result code
  7815. (which will be negative) or the following Scrap Manager result code:
  7816.  
  7817.         CONST noTypeErr = -102;   {no data of the requested type}
  7818.  
  7819. For example, given the declaration
  7820.  
  7821.         VAR pHndl: Handle;      {handle for 'PICT' type}
  7822.         tHndl: Handle;          {handle for 'TEXT' type}
  7823.         length: LONGINT;
  7824.         offset: LONGINT;
  7825.  
  7826. you can make the following calls:
  7827.  
  7828.         pHndl := NewHandle(0);
  7829.         length := GetScrap(pHandl,'PICT',offset);
  7830.         IF length < 0
  7831.           THEN
  7832.            {error-handling}
  7833.           ELSE DrawPicture(PicHandle(pHndl))
  7834.  
  7835.  
  7836.     If your application wants data in the form of a  picture, and the
  7837. scrap contains only text, you can convert the text into a picture by
  7838. doing the following:
  7839.  
  7840.           tHndl := NewHandle(0);
  7841.           length := GetScrap(tHndl,'TEXT',offset);
  7842.           IF length < 0
  7843.             THEN
  7844.               {error-handling}
  7845.             ELSE
  7846.               BEGIN
  7847.               HLock(tHndl);
  7848.               pHndl := OpenPicture(thePort^.portRect);
  7849.               TextBox(tHndl^,length,thePort^.portRect,teJustLeft);
  7850.               ClosePicture;
  7851.               HUnlock(tHndl);
  7852.             END
  7853.  
  7854.  
  7855.     The Memory Manager procedures HLock and HUnlock are used to lock and
  7856. unlock blocks when handles are dereferenced (see the Memory Manager
  7857. Manual).
  7858.  
  7859. (note)
  7860.       To copy the desk scrap to the TextEdit scrap, use the
  7861.       TextEdit function TEFromScrap.
  7862.  
  7863.     Your application should pass its preferred data type to GetScrap. If
  7864. it doesn't prefer one data type over any other, it should try getting
  7865. each of the types it can read, and use the type that returns the lowest
  7866. offset. (A lower offset means that this data type was written before
  7867. the others, and therefore was preferred by the application that wrote
  7868. it.)
  7869.  
  7870. (note)
  7871.       If you're trying to read in a complicated picture, and 
  7872.       there isn't enough room in memory for a copy of it, you
  7873.       can customize QuickDraw's picture retrieval so that
  7874.       DrawPicture will read the picture directly from the scrap
  7875.       file. (QuickDraw also lets you customize how pictures
  7876.       are saved so you can save them in a file; see the
  7877.       QuickDraw manual for details about customizing.)
  7878.  
  7879. (note)
  7880.       When reading in a picture from the scrap, allow a buffer
  7881.       of about 3.5K bytes.  (There's a convention that the
  7882.       application defining the picture won't call the QuickDraw
  7883.       procedure CopyBits for more than 3K, so a 3.5K buffer
  7884.       should be large enough for any picture.
  7885. \ ZeroScrap
  7886. 11
  7887. FUNCTION ZeroScrap : LONGINT;
  7888.  
  7889.     If the scrap already exists (in memory or on the disk), ZeroScrap
  7890. clears its contents; if not, the scrap is initialized in memory. You
  7891. must call ZeroScrap before the first time you call PutScrap. If no
  7892. error occurs, ZeroScrap returns the result code noErr; otherwise, it
  7893. returns an Operating System result code indicating an error.
  7894.  
  7895.     ZeroScrap also changes the scrapCount field of the record of
  7896. information provided by InfoScrap. This is useful for testing whether
  7897. the contents of the desk scrap have changed during the use of a desk
  7898. accessory. The application can save the value of the scrapCount field
  7899. when one of its windows is deactivated and a system window is
  7900. activated. Then, each time through its event loop, it can check to see
  7901. whether the value of the field has changed. If so, it means the desk
  7902. accessory called ZeroScrap (and, presumable, PutScrap) and thus changed
  7903. the contents of the desk scrap.
  7904.  
  7905. (warning)
  7906.          Just check to see whether the scrapCount field has
  7907.          changed; don't rely on exactly how it has changed.
  7908. \ PutScrap
  7909. 11
  7910. FUNCTION PutScrap (length: LONGINT; theType: ResType; source: Ptr) :
  7911.               LONGINT;
  7912.  
  7913.     PutScrap writes the data poointed to by the source parameter to the
  7914. desk scrap (in memory or on the disk). The length parameter indicates
  7915. the number of bytes to write, and theType is the data type.
  7916.  
  7917. (warning)
  7918.         The specified type must be different from the type of any
  7919.         data already in the desk scrap. If you write data of a
  7920.         type already in the scrap, the new data will be appended
  7921.         to the scrap, and subsequent GetScrap calls will still
  7922.         return the old data.
  7923.  
  7924.     If no error occurs, PutScrap returns the result code noErr;
  7925. otherwise, it returns an Operating System result code indicating an
  7926. error, or the following Scrap Manager result code:
  7927.  
  7928.        CONST noScrapErr = -100;  {desk scrap isn't initialized}
  7929.  
  7930. (note)
  7931.       To copy the TextEdit scrap to the desk scrap, use the
  7932.       TextEdit function TEToScrap.
  7933.  
  7934. (warning)
  7935.        Don't forget to call ZeroScrap to initialize the scrap or
  7936.        clear its previous contents.
  7937.  
  7938.  
  7939. \ FixRatio
  7940. 12
  7941. FUNCTION FixRatio (numer,demon: INTEGER) : Fixed;
  7942.  
  7943.     FixRatio returns the fixed-point quotient of numer and denom. Numer
  7944. or denom may be any signed integer. The result is truncated. If denom
  7945. is 0, FixRatio returns $7FFFFFFF with the sign of numer.
  7946. \ FixMul
  7947. 12
  7948. FUNCTION  FixMul (a,b: Fixed) : Fixed;
  7949.  
  7950.     FixMul returns the fixed-point product of a and b. The result is
  7951. computed MOD 65536, and truncated.
  7952. \ FixRound
  7953. 12
  7954. FUNCTION FixRound (x: Fixed) : INTEGER;
  7955.  
  7956.     Given a positive fixed-point number, FixRound rounds it to the
  7957. nearest integer and returns the result. If the value is halfway between
  7958. two integers (.5), it's rounded up. To round a negative fixed-point
  7959. number, multiply by -1, round, then multiply by -1 again.
  7960. \ NewString
  7961. 12
  7962. FUNCTION NewString (theString: Str255) : StringHandle;
  7963.  
  7964.     NewString allocates the specified string as a relocatable object on
  7965. the heap and returns a handle to it.
  7966. \ SetString
  7967. 12
  7968. PROCEDURE SetString (h: StringHandle; theString: Str255);
  7969.  
  7970.     SetString sets the string whose handle is passed in h to the string
  7971. specified by theString.
  7972. \ GetString
  7973. 12
  7974. FUNCTION GetString (stringID: INTEGER) : StringHandle;
  7975.  
  7976.     GetString returns a handle to the string having the given resource
  7977. ID, reading it from the resource file if necessary. It calls the
  7978. Resource Manager function GetResource('STR ',stringID). If the resource
  7979. can't be read, GetString returns NIL.
  7980.  
  7981. (note)
  7982.       If your application uses a large number of strings,
  7983.       storing them in a string list in the resource file will
  7984.       be more efficient. You can access strings in a string
  7985.       list with GetIndString, as described below.
  7986. \ GetIndString
  7987. 12
  7988. PROCEDURE GetIndString (VAR theString: Str255; strListID: INTEGER;
  7989.              Index: INTEGER);    [No trap macro]
  7990.  
  7991.     GetIndString returns in theString a string in the string list that
  7992. has the resource ID strListID. It reads the string list from the
  7993. resource file if necessary, by calling the Resource Manager function
  7994. GetResource('STR#',strListID). It returns the string specified by the
  7995. index parameter, which can range from 1 to the number of strings in the
  7996. list. If the resource can't be read or the index is out of range, the 
  7997. empty string is returned.
  7998. \ Munger
  7999. 12
  8000. FUNCTION Munger (h: Handle; offset: LONGINT; ptrl: Ptr; lenl: LONGINT;
  8001.                     ptr2: Ptr; len2: LONGINT) : LONGINT;
  8002.  
  8003.     Munger (which rhymes with "plunger") lets you manipulate bytes in
  8004. the string of bytes (the "destination string") to which h is a handle.
  8005. The operation starts at the specified byte offset in the destination
  8006. string.
  8007.  
  8008. (note)
  8009.       Although the term "string" is used here, Munger does not
  8010.       assume it's manipulating a Pascal string; if you pass it
  8011.       a handle to a Pascal string, you must take into account
  8012.       the length byte.
  8013.  
  8014.     The exact nature of the operation done by Munger depends on the
  8015. values you pass it in two pointer/length parameter pairs. In general,
  8016. (ptr1,len1) defines a target string to be replaced by the second string
  8017. (ptr2,len2). If these four parameters are all positive and nonzero,
  8018. Munger looks for the target string in the destination string, starting
  8019. from the given offset and ending at the end of the string; it replaces
  8020. the first occurrence it finds with the replacement string and returns
  8021. the offset of the first byte past where the replacement occurred.
  8022. Figure 1 illustrates this; the bytes represent ASCII characters as
  8023. shown.
  8024.  
  8025.     Different operations occur if either pointer is NIL or either length
  8026. is 0:
  8027.  
  8028.     - If ptr1 is NIL, the substring of length len1 starting at the given
  8029.       offset is replaced by the replacement string. If len1 is
  8030.       negative, the substring from the given offset to the end of the
  8031.       destination string is replaced by the replacement string. In
  8032.       either case, Munger returns the offset of the first byte past
  8033.       where the replacement occurred.
  8034.  
  8035.  
  8036.     - If len1 is 0, (ptr2,len2) is simply inserted at the given offset;
  8037.       no text is replaced. Munger returns the offset of the first byte
  8038.       past where the insertion occurred.
  8039.  
  8040.     - If ptr2 is NIL, Munger returns the offset at which the targer
  8041.       string was found. The destination string isn't changed.
  8042.  
  8043.     - If ptr2 is NIL, Munger returns the offset at which the target
  8044.       string was found. The destination string isn't changed.
  8045.  
  8046.     - If len2 is 0 (and ptr2 is not NIL), the target string is deleted
  8047.       rather than replaced (since the replacement string is empty).
  8048.       Munger returns the offset at which the deletion occurred.
  8049.  
  8050.  
  8051.     If it can't find the target string in the destination string, Munger 
  8052. returns a negative value.
  8053.  
  8054.     There's one case in which Munger performs a replacement even if it
  8055. doesn't find all of the target string. If the substring from the
  8056. offset to the end of the destination string matches the beginning of
  8057. the target string, the portion found is replaced with the replacement
  8058. string.
  8059.  
  8060. (warning)
  8061.         Be careful not to specify an offset that's greater than
  8062.         the length of the destination string, or unpredictable
  8063.         results may occur.
  8064.  
  8065. (note)
  8066.         The destination string must be in a relocatable block
  8067.         that was allocated by the Memory Manager. Munger
  8068.         accesses the string's length by calling the Memory
  8069.         Manager routines GetHandleSize and SetHandleSize.
  8070. \ PackBits
  8071. 12
  8072. PROCEDURE PackBits (VAR srcPtr,DstPtr: Ptr; srcBytes: INTEGER);
  8073.  
  8074.     PackBits compresses srcBytes bytes of data starting at srcPtr and
  8075. stores the compressed data at dstPtr. The value of srcBytes should not
  8076. be greater than 127. Bytes are compressed when there are three or more
  8077. consecutive equal bytes. After the data is compressed, srcPtr is
  8078. incremented by srcBytes and dstPtr is incremented by the number of
  8079. bytes that the data was compressed to. In the worst case, the
  8080. compressed data can be one byte longer than the original data.
  8081.  
  8082.     PackBits is usually used to compress QuickDraw bit images; in this
  8083. case, you should call it for one row at a time. (Because of the
  8084. repeating patterns in QuickDraw images, there are more likely to be
  8085. consecutive equal bytes there than in other data.)  Use UnpackBits
  8086. (below) to expand data compressed by PackBits.
  8087. \ UnpackBits
  8088. 12
  8089. PROCEDURE UnpackBits (VAR SrcPtr, DstPtr: Ptr; dstBytes: Integer);
  8090.  
  8091.     Given in SrcPtr a pointer to the data that was compressed by PackBits,
  8092. UnpackBits expands the data and stores the result as DstPtr. DstBytes is
  8093. the length that the expanded data will be; it should be the value that was
  8094. passed to PackBits in the SrcBytes parameter. After the data is expanded,
  8095. srcPtr is incremented by the number of bytes that were expanded and dstPtr
  8096. is incremented by dstBytes.
  8097. \ BitTst
  8098. 12
  8099. FUNCTION BitTst (BytePtr: Ptr; bitNum: Longint): Boolean;
  8100.  
  8101.     BitTst tests wether a given bit is set and returns TRUE if so or FALSE
  8102. if not. The bit is specified by bitNum, an offset from the high-order bit
  8103. of the byte pointed to by BytePtr.
  8104. \ BitSet
  8105. 12
  8106. PROCEDURE BitSet (BytePtr: Ptr; bitNum: Longint);
  8107.  
  8108.     BitSet sets the bit specified by bitNum, an offset from the high-order
  8109. bit of the byte pointed to by BytePtr.
  8110. \ BitClear
  8111. 12
  8112. PROCEDURE BitClear (BytePtr: Ptr; bitNum: Longint);
  8113.  
  8114.     BitClear clears the bit specified by bitNum, an offset from the
  8115. high-order bit of the byte pointed to by BytePtr.
  8116. \ BitAnd
  8117. 12
  8118. FUNCTION BitAnd (Value1, Value2: Longint): Longint;
  8119.  
  8120.     BitAnd returns the value of the AND logical operation on the bits
  8121. comprising the given long integers ( vallue1 AND value2).
  8122. \ BitOr
  8123. 12
  8124. FUNCTION BitOr (Value1, Value2: Longint): Longint;
  8125.  
  8126.     BitOr returns the value of the OR logical operation on the bits
  8127. comprising the given long integers ( vallue1 OR value2).
  8128. \ BitXor
  8129. 12
  8130. FUNCTION BitXor (Value1, Value2: Longint): Longint;
  8131.  
  8132.     BitXor returns the value of the XOR logical operation on the bits
  8133. comprising the given long integers ( vallue1 XOR value2).
  8134. \ BitNot
  8135. 12
  8136. FUNCTION BitNot (Value: Longint): Longint;
  8137.  
  8138.     BitNot returns the result of the NOT logical opeation on the bits
  8139. comprisisng the given long integer (NOT value).
  8140. \ BitShift
  8141. 12
  8142. FUNCTION BitShift (Value: Longint; count: Integers): Longint;
  8143.  
  8144.     BitShift logically shifts the bits of the giveb long integer. The count
  8145. parameter specifies the direction and the extent of the shift, and is token
  8146. MOD 32. If count is positive, BitShift shifts that many positions to the
  8147. left; if count is negative, it shifts to the right. Zeroes are shifted into
  8148. empty positions at their end.
  8149. \ HiWord
  8150. 12
  8151. FUNCTION HiWord (x: Longint): Integer;
  8152.  
  8153.     HiWord returns the high-order word of the given long integer. One use
  8154. of this function is to extract the integer part of a fixed-point number.
  8155. \ LoWord
  8156. 12
  8157. FUNCTION LoWord (x: Longint): Integer;
  8158.  
  8159.     LoWord returns the low-order word of the given long integer. One use
  8160. of this function is to extract the fractional part of a fixed-point number.
  8161.  
  8162.     Note: If you're dealing with a long intger that contains two separate
  8163.     integer values, you can define a variant record instead of using
  8164.     HiWord and LoWord. For example, for fixed-point numbers, you can define
  8165.     the following type:
  8166.  
  8167.       TYPE FixedAndInt = RECORD CASE Integer OF
  8168.                             1: (FixedView: Fixed);
  8169.                             2: (intView:   RECORD
  8170.                                             Whole: Integer;
  8171.                                             Part : Integer;
  8172.                                            END;)
  8173.                           END;
  8174.  
  8175.     If you declare x to be of type FixedAndInt, you can access it as a
  8176.     fixed-point value with x.FixedView, or access the integer part with
  8177.     x.intView.Whole aand the fractional part with x.intView.part.
  8178. \ LongMul
  8179. 12
  8180. PROCEDURE LongMul (a,b: Longint; VAR dest: Int64bit);
  8181.  
  8182.     LongMul multiplies the given long integers and returns the signed
  8183. result in dest which has the following data type:
  8184.  
  8185.     TYPE Int64Bit = RECORD
  8186.                       HiLong: Longint;
  8187.                       LoLong: Longint;
  8188.                     END;
  8189. \ ScreenRes
  8190. 12
  8191. PROCEDURE ScreenRes (VAR scrnHRes, scrnVRes: Integer); [Not in ROM]
  8192.  
  8193.     ScreenRes returns the resolution of the screen of the macintosh being
  8194. used. ScrnHRes and scrnVRes are the number of pixels per inch horizontally
  8195. and verticaly, respectively.
  8196.  
  8197.         ____________________________________________________________
  8198.          Assembly-language note: The number of pixels per  inch
  8199.          horizontally is stored in the global variable ScrHRes, and
  8200.          the number of pixels per inch vertically is stored in
  8201.          ScrVRes.
  8202.         ____________________________________________________________
  8203. \ GetIcon
  8204. 12
  8205. FUNCTION GetIcon (IconId: Integer): Handle;
  8206.  
  8207.     GetIcon returns a handle to the icon having the given resource ID,
  8208. reading it from the resource file if necessary. It calls the resource
  8209. manager function GetResource ('ICON', IconId). If the resource can't be
  8210. read, GetIcon returns NIL.
  8211. \ PlotIcon
  8212. 12
  8213. PROCEDURE PlotIcon (TheRect: Rect; TheIcon: Handle);
  8214.     PlotIcon draws the icon whose handle is theIcon in the rectangle
  8215. TheRect, which is in the local coordinate of the current grafport. It calls
  8216. the QuickDraw procedure CopyBits and uses the srcCopy transfer mode.
  8217. \ GetPattern
  8218. 12
  8219. FUNCTION GetPattern (PatID: Integer): PatHandle;
  8220.  
  8221.     GetPattern returns a handle to the pattern  having the given resource
  8222. ID, reading it from the resource file if necessary. It calls the resource
  8223. manager function  GetResource ('PAT ', PatId). If the resource can't be
  8224. read, GetPattern returns NIL. The PatHandle data type is defined in the
  8225. toolbox utilities as follows:
  8226.  
  8227.     TYPE  PatPtr    = ^Pattern;
  8228.           PatHandle = ^PatPtr;
  8229. \ GetIndPattern
  8230. 12
  8231. Function GetIndPattern (VAR ThePattern: Patter; PatLisId: Integer; Index:
  8232.                         Integer);  [Not in ROM]
  8233.  
  8234.     GetIndPattern returns in the pattern a pattern in the pattern list that
  8235. has the resource ID PatListID. It reads the pattern list from the resource
  8236. file if necessary, by calling the Resource Manager function
  8237. GetResource ('PAT#', PatListID). It returns the pattern specified by the
  8238. index parameter, which can range from 1 to the number of patterns in the
  8239. pattern list.
  8240.  
  8241.     There's a pattern list in the system resource file that contains the
  8242. standard Macintosh patterns used by MacPaint. Its resource ID is :
  8243.  
  8244.     CONST   SysPatListID = 0;
  8245. \ GetCursor
  8246. 12
  8247. FUNCTION GetCursor (CursorID: Integer): CursHandle;
  8248.  
  8249.     GetCursor returns a handle to the cursor having the given resource ID,
  8250. reading it forme the resource file if necessary. It calls the resource
  8251. manager function GetResource ('CURS', CursorIdD). If the resource can't be
  8252. read, GetCursor returns NIL. The CursHandle data type is defined in the
  8253. toolbox utilities as follows:
  8254.  
  8255.     TYPE    CursPtr    = ^Cursor;
  8256.             CursHandle = ^CursPtr;
  8257.  
  8258.     The standard cursors are defined in the system resource file. Their
  8259. resources ID are:
  8260.  
  8261.     CONST   iBeamCursor = 1; {to select text}
  8262.             crossCursor = 2; {to draw graphics}
  8263.             plusCursor  = 3; {to select cells in structured documents}
  8264.             watchCursor = 4; {to indicate a too long wait}
  8265.  
  8266.  
  8267.     Note: You can set the cursor with the quickdraw procedure SetCursor.
  8268.     The arrow cursor is defined in QuickDraw as a global variable named
  8269.     Arrow.
  8270. \ ShieldCursor
  8271. 12
  8272. PROCEDURE ShieldCursor (shieldRect: Rect; OffsetPt: Point);
  8273.  
  8274.     If the cursor and the given rectangle intersect, ShieldCursor hides the
  8275. cursor. If they don't intersect, the cursor remains visible while the mouse
  8276. isn't moving, but is hidden when the mouse moves.
  8277.  
  8278.     Like the QuickDraw procedure HideCursor, ShieldCursor decrements the
  8279. cursor level,  and should be balanced by a call to ShowCursor.
  8280.  
  8281.     The rectangle may be given in local or global coordinates:
  8282.  
  8283. •  If they're global coordinates, pass (0, 0) in OffsePt.
  8284. •  If they're a grafport's local coordinates, pass the top left corner of
  8285.    the grafport's boundary rectangle in OffsetPt. (Like the QuickDraw
  8286.    procedure LocalToGlobal, ShieldCursor will offset the coordinates of
  8287.    the rectangle by the coordinate of this point.)
  8288. \ GetPicture
  8289. 12
  8290. FUNCTION GetPicture (PicID: Integer): PicHandle;
  8291.  
  8292.     GetPicture returns a handle to the picture having the given resource
  8293. ID, reading it from the resource file if necessary. It calls the resource
  8294. Manager function GetResource ('PICT', PicID). If the resource can't be read
  8295. GetPicture returns NIL. The PicHandle data type is defined in QuickDraw.
  8296. \ DeltaPoint
  8297. 12
  8298. FUNCTION DeltaPoint (ptA, ptB: Point): Longint;
  8299.  
  8300.     DeltaPoint substracts the coordinates of ptB from the coordinates of
  8301. ptA. The high-order word of the result is the difference of the vertical
  8302. coordinates, and the low-order word is the difference of the horizontal
  8303. coordinates.
  8304.  
  8305.     NOTE : The QuickDraw procedure SubPt also substracts the coordinates
  8306.     of one point, but returns the result in a VAR parameter of type Point.
  8307. \ SlopeFromAngle
  8308. 12
  8309. FUNCTION SlopeFromAngle (Angle: Integer): Fixed;
  8310.  
  8311.     Given an angle, SlopeFromAngle returns the slope dh/dv of the line
  8312. forming that angle with the Y-axis (dh/dv is the horizontal change divided
  8313. by the vertical  change between any two points on the line). The angle is
  8314. treated MOD 180, and its degrees measured from 12 o'clock; positive degrees
  8315. are measured clockwise, negative degrees are measured counterclockwise (for
  8316. example, 90 degrees is at 3 o'clock, and -90 degrees is at 9 o'clock).
  8317. Positive y is down; positive x is to the right.
  8318. \ AngleFromSlope
  8319. 12
  8320. Function AngleFromSlope (Slope: Fixed): Integer;
  8321.  
  8322.     Given the slope dh/dv of a line (see SlopeFromAngle), AngleFromSlope
  8323. returns the angle formed by that line and the y-axis. The angle returned
  8324. is between 1 and 180 (inclusive), in degrees measured clockwise from 12
  8325. o'clock.
  8326.  
  8327.     AngleFromSlope is meant for use when speed is much more important than
  8328. accuracy - its integer result is guaranted to be one degree of the correct
  8329. answer,  but not necessarily within half a degree. However the equation
  8330.  
  8331.     AngleFromSlope(SlopeFromAngle(x))= x
  8332.  
  8333. is true for all x except 0 (although reverse is not).
  8334.  
  8335.     NOTE : SlopeFromAngle(0) is 0, and AngleFromSlope(0) is 180.
  8336. \ FracMul
  8337. 12
  8338. FUNCTION FracMul (x,y: Fract) : Fract;
  8339.  
  8340. FracMul returns x * y. Note that FracMul effects
  8341.  
  8342. “type   *   Fract   —>  type”:
  8343. Fract   *   Fract   —>  Fract
  8344. LONGINT *   Fract   —>  LONGINT
  8345. Fract   *   LONGINT —>  LONGINT
  8346. Fixed   *   Fract   —>  Fixed
  8347. Fract   *   Fixed   —>  Fixed
  8348. \FixDiv
  8349. 12
  8350. FUNCTION FixDiv (x,y: Fixed) : Fixed;
  8351.  
  8352. FixDiv returns x / y.
  8353. \FracDiv
  8354. 12
  8355. FUNCTION FracDiv (x,y: Fract) : Fract;
  8356.  
  8357. FracDiv returns x / y.
  8358. \FracSqrt
  8359. 12
  8360. FUNCTION FracSqrt (x: Fract) : Fract;
  8361.     FracSqrt returns the square root of x, with x interpreted as
  8362. unsigned in the range 0 through 4–(2–30), inclusive:  That is, bit 15 in
  8363. Figure 1 has weight 2 rather than –2. The result, too, is unsigned
  8364. in the range 0 through 2, inclusive.
  8365. \FracCos
  8366. 12
  8367. FUNCTION FracCos (x: Fixed) : Fract;
  8368.     FracCos and FracSin return the cosine and sine of their radian
  8369. arguments, respectively. The hexadecimal value 0.C910 (which is
  8370. FixATan2(1,1)) is the approximation to π/4 used for argument reduction.
  8371. Thus, FracCos and FracSin are nearly periodic, but with period 2*P
  8372. instead of 2*π, where P=3.1416015625 and π, of course, is 3.14159265....
  8373. \FracSin
  8374. 12
  8375. FUNCTION FracSin (x: Fixed) : Fract;
  8376.  
  8377.     FracCos and FracSin return the cosine and sine of their radian
  8378. arguments, respectively. The hexadecimal value 0.C910 (which is
  8379. FixATan2(1,1)) is the approximation to π/4 used for argument reduction.
  8380. Thus, FracCos and FracSin are nearly periodic, but with period 2*P
  8381. instead of 2*π, where P=3.1416015625 and π, of course, is 3.14159265....
  8382. \FixATan2
  8383. 12
  8384. FUNCTION FixATan2 (x,y: LONGINT) : Fixed;
  8385.  
  8386.     FixATan2 returns the arctangent of y / x in radians.
  8387. \Long2Fix
  8388. 12
  8389. FUNCTION Long2Fix (x: LONGINT) : Fixed;
  8390.  
  8391.     Long2Fix, Fix2Long, Fix2Frac, and Frac2Fix convert between
  8392. fixed-point types.
  8393. \Fix2Long
  8394. 12
  8395. FUNCTION Fix2Long (x: Fixed) : LONGINT;
  8396.  
  8397. Long2Fix, Fix2Long, Fix2Frac, and Frac2Fix convert between fixed-point
  8398. types.
  8399. \Fix2Frac
  8400. FUNCTION Fix2Frac (x: Fixed) : Fract;
  8401.  
  8402. Long2Fix, Fix2Long, Fix2Frac, and Frac2Fix convert between fixed-point
  8403. types.
  8404. \Frac2Fix
  8405. 12
  8406. FUNCTION Frac2Fix (x: Fract) : Fixed;
  8407.  
  8408. Long2Fix, Fix2Long, Fix2Frac, and Frac2Fix convert between fixed-point
  8409. types.
  8410.  
  8411. \Fix2X
  8412. 12
  8413. FUNCTION Fix2X  (x: Fixed) : Extended;
  8414.  
  8415. Fix2X, X2Fix, Frac2X, and X2Frac convert between Fixed and Fract
  8416. and the Extended floating-point type. These functions do not set
  8417. floating-point exception flags.
  8418. \X2Fix
  8419. 12
  8420.  
  8421. Fix2X, X2Fix, Frac2X, and X2Frac convert between Fixed and Fract
  8422. and the Extended floating-point type. These functions do not set
  8423. floating-point exception flags.
  8424. FUNCTION X2Fix  (x: Extended) : Fixed;
  8425. \Frac2X
  8426. 12
  8427. FUNCTION Frac2X (x: Fract) : Extended;
  8428.  
  8429. Fix2X, X2Fix, Frac2X, and X2Frac convert between Fixed and Fract
  8430. and the Extended floating-point type. These functions do not set
  8431. floating-point exception flags.
  8432. \X2Frac
  8433. 12
  8434. FUNCTION X2Frac (x: Extended) : Fract;
  8435.  
  8436. Fix2X, X2Fix, Frac2X, and X2Frac convert between Fixed and Fract
  8437. and the Extended floating-point type. These functions do not set
  8438. floating-point exception flags.
  8439.  
  8440. \ InitPack
  8441. 13
  8442. PROCEDURE InitPack (packID: INTEGER);
  8443.  
  8444.     InitPack enables you to use the package specified by packID, which
  8445. is the package's resourceID. (It gets a handle that will be used later
  8446. to read the package into memory.)
  8447. \ InitAllPacks
  8448. 13
  8449. PROCEDURE InitAllPacks;
  8450.  
  8451.     InitAllPacks enables you to use all Macintosh packages (as though
  8452. InitPack were called for each one). It wil already have been called
  8453. when your application starts up.
  8454. \ IUDateString
  8455. 13
  8456. PROCEDURE IUDateString (dateTime: LongInt; form: DateForm; VAR result:
  8457.                         Str255);
  8458.  
  8459.     Given a date and time as returned by the Operating System Utility
  8460. routine ReadDateTime, IUDateString returns in the result parameter a
  8461. string that represents the corresponding date. The form parameter has
  8462. the following data type:
  8463.  
  8464.        TYPE DateForm = (shortDate,longDate,abbrevDate);
  8465.  
  8466.     ShortDate requests the short date format, longDate the long date,
  8467. and abbrevDate the abbreviated long date. IUDateString determines the
  8468. exact format from international resource 0 for the short date of 1 for
  8469. the long date. See Figure I-1 above for examples of the standard
  8470. formats. Notice that the short date contains a space in place of  a
  8471. leading zero when the format specifies "no leading zero", so the length
  8472. of the result is always the same for short dates.
  8473.  
  8474.     If the abbreviated long date is requested and the abbreviation
  8475. length in international resource 1 is greater than the actual length of
  8476. the name being abbreviated, IUDateString fills the abbreviation with NUL
  8477. characters; the abbreviation length should not be greater than 15, the
  8478. maximum name length.
  8479. \ IUDatePString
  8480. 13
  8481. PROCEDURE IUDatePString (dateTime: LongInt; form: DateForm; VAR result:
  8482.             Str255; intlParam: Handle);
  8483.  
  8484.  
  8485.     IUDatePString is the same as IUDateString except that it determines
  8486. the exact format of the date from the resource whose handle is passed in
  8487. intlParam, overriding the resource that would otherwise be used.
  8488. \ IUTimeString
  8489. 13
  8490. PROCEDURE IUTime STring (dateTime: LongInt; wantSeconds: BOOLEAN; VAR
  8491.             result: Str255);
  8492.  
  8493.     Given a date and time as returned by the Operating System Utility
  8494. routein ReadDateTime, IUTimeString returns in the result parameter a
  8495. string that represents the corresponding time of day. If wantSeconds
  8496. is TRUE, seconds are included in the time; otherwise, only the hour and
  8497. minute are included. IUTimeSting determines the time format from
  8498. internation resource 0. See Figure I-1 above for examples of the
  8499. standard formats. Notice that the time contains a space in place of a
  8500. leading zero when the format specifies "no leading zero", so the length
  8501. of the result is always the same.
  8502. \ IUTimePString
  8503. 13
  8504. PROCEDURE IUTimePString (dateTime: LongInt; wantSeconds: BOOLEAN; VAR
  8505.             result: str255; intlParam: Handle);
  8506.  
  8507.     IUTimePString is the same as IUTimeString except that it determines
  8508. the time format from the resource whose handle is passed in intlParam,
  8509. overriding the resource that would otherwise be used.
  8510. \ IUMetric
  8511. 13
  8512. FUNCTION IUMetric : BOOLEAN;
  8513.  
  8514.     If international resource 0 specifies that the metric system is to
  8515. be used, IUMetric retruns TRUE; otherwise, it returns FALSE.
  8516. \ IUGetIntl
  8517. 13
  8518. FUNCTION IUGetIntl (theID: INTEGER) : Handle;
  8519.  
  8520.     IUGetIntl returns a handle to the international resource numbered
  8521. theID (0 or 1). It calls the Resource Manager function
  8522. GetResource('INTL',theID). For example, if you want to access
  8523. individual fields of international resource 0, you can do the
  8524. following:
  8525.  
  8526.      VAR myHndl: Handle;
  8527.          int0: Intl0Hndl;
  8528.      ...
  8529.      myHndl := IUGetIntl(0);
  8530.      int0 := POINTER(ORD(myHndl));
  8531. \ IUSetIntl
  8532. 13
  8533. PROCEDURE IUSetIntl (refNum: INTEGER; thefID; INTEGER; intlParam:
  8534.             Handle);
  8535.  
  8536.     In the resource file having the reference number refNum, IUSetIntl
  8537. sets the international resource numbered theID (0 or 1) to the data
  8538. pointed to by tintlParam. The data may be either an existing resource
  8539. okr data that hasn't yet been written to a resource file. IUSetIntl
  8540. adds the resource to the specified file or replaces the resource if it's
  8541. already there.
  8542. \ IUCompString
  8543. 13
  8544. FUNCTION IUCompString (aStr,bStr: Str255) : INTEGER;  [Pascal only]
  8545.  
  8546.     IUCompString compares aStr and bStr as described above under
  8547. "International String Comparison", taking both primary and secondary
  8548. ordering into consideration. It returns one of the values listed
  8549. below.
  8550.  
  8551.       Result   Meaning                           Example
  8552.                                               aStr     bStr
  8553.        -1       aStr is less than bStr       'Ab'     'ab'
  8554.         0       aStr  equals bStr            'Ab'     'Ab'
  8555.         1       aStr is greater than bStr    'Ac'     'ab'
  8556. \ IUMagString
  8557. 13
  8558. FUNCTION IUMagString (aPtr,bPtr: Ptr; aLen,bLen: INTEGER) : INTEGER;
  8559.  
  8560.     IUMagString is the same as IUCompString (above) except that instead
  8561. of comparing two Pascal strings, it compares the string defined by aPtr
  8562. and aLen to the string defined by bPtr and bLen. The pointer points to
  8563. the first character of the string (any byte in memory, not necesarily
  8564. word-aligned), and the length specifies the number of characters in the
  8565. string.
  8566. \ IUEqualString
  8567. 13
  8568. FUNCTION IUEqualString (aStr,bStr: Str255) : INTEGER;   [Pascal only]
  8569.  
  8570.     IUEqualString comapares aStr and bStr for equality without regard
  8571. for secondary ordering, as described above under "international String
  8572. Comparison". If the strings are equal, it returns 0; otherwise, it
  8573. returns 1. For example, if the strings are 'Rose' and 'rose',
  8574. IUEqualString considers them equal and returns 0.
  8575.  
  8576. (note)
  8577.       See also EqualString in the Operating System Utilities
  8578.       manual *** doesn't yet exist***.
  8579. \ IUMagIDString
  8580. 13
  8581.     IUMagIDString is the same as IUEqualString (above) except that
  8582. instead of comparing two Pascal strings, it compares the string defined
  8583. by aPtr and aLen to the string defined by bPtr and bLen. The pointer
  8584. points to the first character of the string (any byte in memory, not
  8585. necessarily word-aligned), and the length specifies the number of4
  8586. characters in the string.
  8587. \ NumToString
  8588. 13
  8589. PROCEDURE NumToString (theNum: LongInt; VAR theStringd: Str255);
  8590.  
  8591. ____________________________________________________________________
  8592.  
  8593. Trap macro     _NumToString
  8594.  
  8595. On entry       A0:  pointer to theString (length byte followed
  8596.                   by characters)
  8597.  
  8598.              D0:  theNum (long integer)
  8599.  
  8600. On exit         A0:  pointer to theString
  8601.  
  8602. _____________________________________________________________________
  8603.  
  8604.     NumToString converts theNum to a string that represents its decimal
  8605. value, and returns the result in theString. If the value is negative,
  8606. the string begins with a minus sign; otherwise, the sign is omitted.
  8607. Leading zeroes are suppressed, except that the value 0 produces '0'.
  8608. For example:
  8609.  
  8610.      theNum          theString
  8611.       12              '12'
  8612.      -23             '-23'
  8613.        0              '0'
  8614. \ StringToNum
  8615. 13
  8616. PROCEDURE StringToNum (theString: Str255; VAR theNum: LongInt);
  8617.  
  8618. ___________________________________________________________________
  8619.  
  8620. Trap macro     _StringToNum
  8621.  
  8622. On entry       A0:  pointer to theString (length byte followed
  8623.                   by characters)
  8624.  
  8625. On exit        DO:  theNum (long integer)
  8626.  
  8627. ___________________________________________________________________
  8628.  
  8629.  
  8630.     Given a string representing a decimal integer, StringToNum converts
  8631. it to the corresponding integer and returns the result in theNum. The
  8632. string may begin with a plus or minus sign. For example:
  8633.  
  8634.       theString          theNum
  8635.         '12'               12
  8636.        '-23'              -23
  8637.         '-0'                0
  8638.        '055'               55
  8639.  
  8640.     The magnitude of the integer is converted modulo 2^32, and the
  8641. 32-bit result is negated if the string begins with a minus sign; integer
  8642. overflow occurs if the magnitude is greater than 2^31-1. (Negation is
  8643. done by taking the two's complement--reversing the state of each bit
  8644. adn then ading 1.)  For example:
  8645.  
  8646.         theString                                   theNum
  8647.        '2147483648'  (magnitude is 2^31)          -2147483648
  8648.       '-2147483648'                               -2147483648
  8649.        '4294967295'  (magnitude is 2^31)              -1
  8650.       '-4294967295'                                    1
  8651.  
  8652.     StringToNum doesn't actually check whether the characters in the
  8653. string are between '0' and '9'; instead, since the ASCII codes for '0'
  8654. through '9' are $30 through $39, it just masks off the last four bits
  8655. and uses them as a digit. For example, '2:' is converted to the number
  8656. 30 because the ASCI code for ':' is $3A. Leading spaces before the
  8657. first digit are treated as zeroes, since the ASCII code for a space is
  8658. $20. Given that the ASCII codes for 'C', 'A', and 'T' are $43, $41, and
  8659. $54, respectively, consider the following examples:
  8660.  
  8661.  
  8662.       theString              theNum
  8663.         'CAT'                  314
  8664.        '+CAT'                  314
  8665.        '-CAT'                 -314
  8666. \ SFPutFile
  8667. 13
  8668. PROCEDURE SFPutFile (where: Point; prompt: Str255; origName: Str255;
  8669.                     dlgHook: ProPtr; VAR reply: SFReply);
  8670.  
  8671.     SFPutFile displays a dialog box allowing the user to specify a file
  8672. to which data will be written (as during a Save or Save As command). It
  8673. then repeatedly gets and handles events until the user either confirms
  8674. the command after entering an appropriate file name or aborts the
  8675. command by clicking Cancel in the dialog. It reports the user's reply
  8676. by filling the fields of the reply record specified by the reply
  8677. parameter, as described above; the fType field of this record isn't
  8678. used.
  8679.  
  8680.     The general appearance of the standard SFPutFile dialog box is shown
  8681. in Figure S-2. The where parameter specifies the location of the top
  8682. left corner of the dialog box in global coordinates. The prompt
  8683. parameter is a line of text to be displayed as a statText item in the
  8684. dialog box, where shown in Figure S-2. The origName parameter contains
  8685. text that appears as an enabled, selected editText item; for the
  8686. standard document-saving commands, it should be the current name of the
  8687. document, or the empty string (to display an insertion point) if the
  8688. document hasn't been named yet.
  8689.  
  8690.     If you want to use the standard SFPutFile dialog box, pass NIL for
  8691. dlgHook; otherwise, see the information for advanced programmers below.
  8692.  
  8693.     SFPutFile  repeatedly calls the Dialog Manager procedure
  8694. ModalDialog. When an event involving an enabled dialog item occurs,
  8695. ModalDialog handles the event andf returns the item number, and
  8696. SFPutFile responds as follows:
  8697.  
  8698.    - If the Eject or Drive button is clicked, or a disk is inserted,
  8699.      SFPutFile responds as described above under "About the Standard
  8700.      File Package".
  8701.  
  8702.    - Text entered into the editText item is stored in the fName field
  8703.      of the reply record. (SFPutFile keeps track of whetehr there's
  8704.      currently any text in the item, and makes the Save button inactive
  8705.      if not.)
  8706.  
  8707.    - If the Save button is clicked, SFPutFile determines whether the
  8708.      file name in the fName field of the reply record is appropriate.
  8709.      If so, it returns control to the application with the first field
  8710.      of the reply record set to TRUE; otherwise, it responds
  8711.      accordingly, as described below.
  8712.  
  8713.   - If the Cancel button in the dialog is clicked, SFPutFile returns
  8714.     control to the application with the first field of the reply
  8715.     record set to FALSE.
  8716.  
  8717. (note)
  8718.        Notice that disk insertion is one of the user actions
  8719.        listed above, even though ModalDialog normally ignores
  8720.        disk-inserted events. The reason this works is that
  8721.        SFPutFile calls ModalDialog with a filterProc function
  8722.        that checks for a disk-inserted event and returns a
  8723.        "fake", very large item number if one occurs; SFPutFile
  8724.        recognizes this item number as an indication that a disk
  8725.        was inserted.
  8726.  
  8727.     The situations that may cause an entered name to be inappropriate,
  8728. and SFPutFile's response to each, are as follows:
  8729.  
  8730.      - If a file with the specified name already exists on the disk and
  8731.        is different from what was passed in the origName parameter, the
  8732.        alert in Figure S-3 is displayed. If the user clicks Yes, the
  8733.        file name is appropriate.
  8734.  
  8735.      - If the disk to which the file shoud be written is locked, the
  8736.        alert in Figure S-4 is displayed. If a system error occurs, a
  8737.        similar alert is displayed, with a corresponding message
  8738.        explaining the problem.
  8739.  
  8740. (note)
  8741.        The user may specify a disk name (preceding the file name
  8742.        and separated from it by a colon). If the disk isn't
  8743.        currently in a drive, an alert similar to the one in
  8744.        Figure S-4 is displayed. The ability to specify a disk
  8745.        name is supported for historical reasons only; users
  8746.        should not be encouraged to do it.
  8747.  
  8748.     After the user clicks No or Cancel in response to one of these
  8749. alerts, SFPutFile dismisses the alert box and continues handling events
  8750. (so a different name may be entered).
  8751.  
  8752. Advanced programmers:  You can create your own dialog box rather than
  8753. use the standard SFPutFile dailog. To do this, you must provide your
  8754. own dialog template and store it in your application's resource file
  8755. with the same resource ID that the standard template has in the system
  8756. resource file:
  8757.  
  8758.         CONST putDlgID = -3999;   {SFPutFile dialog template ID}
  8759.  
  8760. (note)
  8761.        The SFPPutFile procedure, described below lets you use
  8762.        any resource ID for your nonstandard dialog box.
  8763.  
  8764.     Your dialog template must specify that the dialog window be
  8765. invisible, and your dialog must contain all the standard items, as
  8766. listed below. The appearance and location of these items in your dialog
  8767. may be different. You can make an item "invisible" by giving it a
  8768. display rectangle that's off the screen. The display rectangle for each
  8769. item in the standard dialog box is given below. The rectangle for the
  8770. standard dialog box itself is (0,0,304,104).
  8771.  
  8772.  
  8773.    Item Number  Item                     Standard display rectangle
  8774.     1       Save button                  (12,74,82,92)
  8775.     2       Cancel button                (114,74,184,92)
  8776.     3       Prompt string (statText)     (12,12,184,28)
  8777.     4       UserItem for disk name       (209,16,295,34)
  8778.     5       Eject button                 (217,43,287,61)
  8779.     6       Drive button                 (217,74,287,92)
  8780.     7       EditText item for file name  (14,34,182,50)
  8781.     8       UserItem for gray line       (200,16,201,88)
  8782.  
  8783.  
  8784. (note)
  8785.        Remember that the display rectangle for any "invisible"
  8786.        item must be at least about 20 pixels wide. *** This
  8787.        will be discussed in a future draft of the Dialog Manager
  8788.        manual. ***
  8789.  
  8790.  
  8791.     If your dialog has addition items beyond the standard ones, or if
  8792. you want to handle any of the standard items in a nonstandard manner,
  8793. you must write your own dlgHook funciton and point to it with dlgHook.
  8794. Your dlgHook function should have two parameters and return an integer
  8795. value. For example, this is how it wokuld be declared if it were named
  8796. MyDlg:
  8797.  
  8798.        FUNCTION MyDlg (item: INTEGER; theDialog: DialogPtr) : INTEGER;
  8799.  
  8800.     Immediately after calling ModalDialog, SFPutFile calls your dlgHook
  8801. function, passing it the item number returned by ModalDialog and a
  8802. pointer to the dialog record describing your dialog box. Using these
  8803. two parameters, your dlgHook function should determine how to handle
  8804. the event. There are predefined constants for the item numbers of
  8805. standard enabled items, as follows:
  8806.  
  8807.       CONST putSave   = 1;   {Saver button}
  8808.             putCancel = 2;   {Cancel button}
  8809.         putEject  = 5;   {Eject button}
  8810.         putDrive  = 6;   {Drive button}
  8811.         putName   = 7;   {editText item for file name}
  8812.  
  8813.     ModalDialog also returns the "fake" item number 100 when a disk-
  8814. inserted event occurs, as detected by its filterProc function.
  8815.  
  8816.     After handling the event (or, perhaps, after ignoring it) the
  8817. dlgHook function must return an item number to SFPutFile. If the item
  8818. number is one of those listed above, SFPutFile responds in the standard
  8819. way; otherwise, it does nothing.
  8820.  
  8821. (note)
  8822.        For advanced programmers who want to change the
  8823.        appearance of the alerts displayed when an inappropriate
  8824.        file name is entered, the resource IDs of those alerts in
  8825.        the system resource file are listed below.
  8826.  
  8827.  
  8828.        Alert                   Resource ID
  8829.        Existing file             -3996
  8830.        Locked disk               -3997
  8831.        System error              -3995
  8832.        Disk not found            -3994
  8833. \ SFPPutFile
  8834. 13
  8835. PROCEDURE SFPPutFile (where: Point; prompt: SStr255; origNmae: Str255;
  8836.              dlgHook: ProcPtr; VAR reply: SFReply; dlgID: INTEGER;
  8837.          filterProc: ProcPtr);
  8838.  
  8839.     SFPPutFile is an alternative to SFPutFile for advanced programmers
  8840. who want to use a nonstandard dialog box. It's the same as SFPutFile
  8841. except for the two additional parameters dlgID and filterProc.
  8842.  
  8843.     DlgID is the resource ID of the dialog template to be used instead
  8844. of the standard one (so you can use whatever ID you wish rather than the
  8845. same one as the standard).
  8846.  
  8847.     The filterProc parameter determines how ModalDialog will filter
  8848. events when called by SFPPutFile. If filterProc is NIL, ModalDialog
  8849. does the standard filtering that it does when called by SFPutFile;
  8850. otherwise, filterProoc should point to a function for ModalDialog to
  8851. execute afterdoing the standard filterilng. THe function must be the
  8852. same as one you'd pass directly to ModalDialog in its filterProc
  8853. parameter. (See the Dialog Manager manual for more information.)
  8854. \ SFGetFile
  8855. 13
  8856. PROCEDURE SFGetFile (where: Point; prompt: Str255; fileFilter: ProcPtr;
  8857.                     numTypes: INTEGER; typeList: SFTypeList;
  8858.                     dlgHook: ProcPtr; VAR reply: SFReply);
  8859.  
  8860.     SFGetFIle displays a dialog box listing the names of a specific
  8861. group of files from which the user can select one to be opened (as
  8862. during an Open command). It then repeatedly gets and handles events
  8863. until the user either confirms the command after choosing a file name or
  8864. aborts the command by clicking Cancel in the dialog. It reports the
  8865. user's reply by filling the fields of the reply record specified by the
  8866. reply parameter, as described above under "Using the Standard File
  8867. Package".
  8868.  
  8869.     The general appearance of the standard SFGetFile dialog box is shown
  8870. in Figure S-5. File names are sorted in order of the ASCII codes of
  8871. their characters, ignoring diacritical marks and mapping lowercase
  8872. characters to their uppercase equivalents. If there are more file names
  8873. than can be displayed at one time, the scroll bar is active; otherwise,
  8874. the scroll bar is inactive.
  8875.  
  8876.     The where parameter specifies the  location of the top left corner
  8877. of the dialog box in global coordinates. The prompt parameter is
  8878. ignored; it's there for historical purposes only.
  8879.  
  8880.     The fileFilter, numTypes, and typeList parameters determine which
  8881. files appear in the dialog box. SFGetFile first looks at numTypes and
  8882. typeList to determine what types of files to display, then it executes
  8883. the function pointed to by fileFilter (if any) to do additional
  8884. filtering on which files to display. File types are discussed in the
  8885. manual THE STRUCTURE OF A MACINTOSH APPLICATION. For example, if the
  8886. applicaiton is concerned only with pictures, you won't want to display
  8887. the names of any text files.
  8888.  
  8889.     Pass -1 for numTypes to display all types of files; otherwise, pass
  8890. the number of file types you want to display, and pas the types
  8891. themselves in typeList. The SFTypeList data type is defined as follows:
  8892.  
  8893.          TYPE SFTypeList = ARRAY [0..3] OF OSTYPE;
  8894.  
  8895. (note)
  8896.        This array is declared for a reasonable maximum number of
  8897.        types (four). If you need to specify more than four
  8898.        types, declare your own array type with the desired
  8899.        number of entries (and use the @ operator to pass a
  8900.        pointer to it).
  8901.  
  8902.     If fileFilter isn't NIL, SFGetFile executes the function it points
  8903. to for each file, to determine whether the file should be displayed.
  8904. The fileFilter function has one parameter and returns a Boolean value.
  8905. For example:
  8906.  
  8907.          FUNCTION MyFileFilter (paramBlock: ParmBlkPtr) : BOOLEAN;
  8908.  
  8909.     SFGetFile passes this function the file information it gets by
  8910. calling the File Manager procedure PBGetFInfo. The function selects
  8911. which files should appear in the dialog by returning FALSE for every
  8912. file that should be shown and TRUE for every file that shouldn't be
  8913. shown.
  8914.  
  8915. (note)
  8916.        As described in the File Manager manual, a flag can be
  8917.        set that tells the Finder not to display a particular
  8918.        file's icon on the desktop; this has no effect on whether
  8919.        SFGetFile will list the file name.
  8920.  
  8921.     If you want to use the standard SFGetFile dialog box, pass NIL for
  8922. dlgHook; otherwise, see the information for advanced programmers below.
  8923.  
  8924.     Like SFPutFile, SFGetFile repeatedly calls the Dialog Manager
  8925. procedure ModalDialog. When an event involving an enabled dialog item
  8926. occurs, ModalDialog handles the event and returns the item number, and
  8927. SFGetFile responds as follows:
  8928.  
  8929.    - If the Eject or Drive button is clicked, or a disk is inserted,
  8930.      SFGetFile responds as described above under "About the Standard
  8931.      File Package".
  8932.  
  8933.    - If clicking or dragging occurs in the scroll bar, the contents of
  8934.      the dialog box are redrawn accordingly.
  8935.  
  8936.    - If a file name is clicked, it's selected and stored in the fName
  8937.      field of the reply record. (SFGetFile keeps track of whether a
  8938.      file name is currently selected, and makes the Open button
  8939.      inactive if not.)
  8940.  
  8941.    - If the Open button is clickd, SFGetFile returns control to the
  8942.      application with the first field of the reply record set to TRUE.
  8943.  
  8944.    - If a file name is double-clicked, SFGetFile responds as if the
  8945.      user clicked the file name and then the Open button.
  8946.  
  8947.    - If the Cancel button in the dialog is clicked, SFGetFile returns
  8948.      control to the application with the first field of the reply
  8949.      record set to FALSE.
  8950.  
  8951.     If a key (other than a modifier key) is pressed, SFGetFile selects
  8952. the first file name starting with the character typed. If no file name
  8953. starts with that character, it selects the first file name starting
  8954. with a character whose ASCII code is greater than the character typed.
  8955.  
  8956. Advanced programmers:  You can create your own dialog box rather than
  8957. use the  standard SFGetFile dialog. To do this, you must provide your
  8958. own dialog template and store it in your application's resource file
  8959. with the same resource ID that the standard template has in the system
  8960. resource file:
  8961.  
  8962.         CONST getDlgID = -4000;   {SFGetFile dialog template ID}
  8963.  
  8964. (note)
  8965.       THe SFPGetFile procedure, described below, lets you use
  8966.       any resource ID for your nonstandard dialog box.
  8967.  
  8968.  
  8969.     Your dialog template must specify that the dialog window be
  8970. invisible, and your dialog must contain all the standard items, as
  8971. listed below. The appearance and location of these items in your dialog
  8972. may be different. You can make an item "invisible" by giving it a
  8973. display rectangle that's off the screen. The display rectangle for each
  8974. in the standard dialog box is given below. THe rectangle for the
  8975. standard dialog box itself is (0,0,348,136).
  8976.  
  8977.  Item Number    Item                     Standard display rectangle
  8978.     1         Open button                     (152,28,232,46)
  8979.     2         Invisible button                (1152,59,1232,77)
  8980.     3         Cancel button                   (152,90,232,108)
  8981.     4         UserItem for disk name          (248,28,344,46)
  8982.     5         Eject button                    (256,59,336,77)
  8983.     6         Drive button                    (256,90,336,108)
  8984.     7         UserItem for file name list     (12,11,125,125)
  8985.     8         UserItem for scroll bar         (124,11,140,125)
  8986.     9         UserItem for gray line          (244,20,245,116)
  8987.    10         Invisible text (statText)       (1044,20,1145,116)
  8988.  
  8989.     If your dialog has additional items beyond the standard ones, or if
  8990. you want to handle any of the standard items in a nonstandard manner,
  8991. you must write your own dlgHook function and point to it with dlgHook.
  8992. Your dlgHook function should have two parameters and return an integer
  8993. value. For example, this is how it would be declared if it were named
  8994. MyDlg:
  8995.  
  8996.        FUNCTION MyDlg (item: INTEGER; theDialog: DialogPtr) : INTEGER;
  8997.  
  8998.     Immediately after calling ModalDialog, SFGetFile calls you dlgHook
  8999. function, passing it the item number returned by ModalDialog and a
  9000. pointer to the dialog record describing you dialog box. Using these
  9001. two parameters, your dlgHook function should determine how to handle
  9002. the event. There are predefined constants for the item numbers of
  9003. standard enabled items, as follows:
  9004.  
  9005.     CONST getOpen    = 1;   {Open button}
  9006.           getCancel  = 3;   {Cancel button}
  9007.       getEject   = 5;   {Eject button}
  9008.       getDrive   = 6;   {Drive button}
  9009.       getNmList  = 7;   {userItem for file name list}
  9010.       getScroll  = 8;   {userItem for scroll bar}
  9011.  
  9012.     ModalDIalog also returns "fake" item numbers in the following
  9013. situations, which are detected by its filterProc function:
  9014.  
  9015.    - When a disk-inserted event occurs, it returns 100.
  9016.  
  9017.    - When a key-down event occurs, it returns 1000 plus the ASCII code
  9018.      of the character.
  9019.  
  9020.     After handling the event (or, perhaps, after ignoring it) your
  9021. dlgHook function must return an item number to SFGetFile. If the item
  9022. number is one of those listed above, SFGetFile responds in the standard
  9023. way; otherwise, it does nothing.
  9024. \ SFPGetFile
  9025. 13
  9026. PROCEDURE SFPGetFile (where: Point; prompt: Str255; fileFilter:
  9027.             ProcPtr; numTypes: INTEGER; typeList: SFTypeList; dlgHook:
  9028.         ProcPtr; VAR reply: SFReply; dlgID: INTEGER; filterProc:
  9029.         ProcPtr);
  9030.  
  9031.     SFPGetFile is an alternative to SFGetFile for advanced programmers
  9032. who want to use a nonstandard dialog box. It's the same as  SFGetFile
  9033. except for the two additional parameters dlgID and filterProc.
  9034.  
  9035.     DlgID is the rexource ID of the dialog template to be used instead
  9036. of the standard one (so you can use whatever ID you wish rather than the
  9037. smae one as the standard).
  9038.  
  9039.     The filterProc parameter determines how ModalDialog will filter
  9040. events when called by SFPGetFile. If filterProc is NIL, ModalDialog
  9041. does the standard filtering that it does when called by SFGetFile;
  9042. otherwise, filterProc should point to a function for ModalDialog to
  9043. execute after doing the standard filtering. Note, however, that the
  9044. standard filtering will detect key-down events only if the dialog
  9045. template ID is the standard one.
  9046. \ DILoad
  9047. 13
  9048. PROCEDURE DILoad;
  9049.  
  9050.     DILoad reads the Disk Initialization Package, and its associated
  9051. dialog and dialog items, from the system resource file into memory and
  9052. makes them unpurgeaable.
  9053.  
  9054. (note)
  9055.        DIFormat, DIVerify, and DIZero don't need the dialog, so
  9056.        if you use only these routines you can call the Resource
  9057.        Manager function GetResource to read just the package
  9058.        resource into memory (and the Memory Manager procedure
  9059.        HNoPurge to make it unpurgeable).
  9060. \ DIUnload
  9061. 13
  9062. PROCEDURE DIUnload;
  9063.  
  9064.     DIUnload makes the Disk Initialization Package (and its associated
  9065. dialog an dialog items) purgeable.
  9066. \ DIBadMount
  9067. 13
  9068. FUNCTION DIBadMount (where: Point; evtMessage: LongInt) : INTEGER;
  9069.  
  9070.     Call DIBadMount when a disk-inserted event occurs if the result code
  9071. in the high-order word of the associated event message indicates an
  9072. error (that is, the result code is other than noErr). Given the event
  9073. message in evtMessage, DIBadMount evaluates the result code and either
  9074. ejects the disk or lets the user initialize and name it. The low-order
  9075. word of the event message contains the drive number. The where
  9076. parameter specifies the location (in global coordinates) of the top
  9077. left corner of the dialog box displayed by DIBadMount.
  9078.  
  9079.     If the result code passed is extFSErr, mFulErr, nsDrvErr, paramErr
  9080. , or volOnLinErr, DIBadMount displays a dialog box that describes the
  9081. problem and asks whether the user wants to initialized the disk. For
  9082. the result code ioErr, the dialog box shown in Figure D-1 is displayed.
  9083. (This happens if the disk is brand new.)  For badMDBErr and noMacDskErr,
  9084. DIBadMount displays a similar dialog box in which the description of
  9085. the problem is "This disk is damaged" and "This is not a Macintosh
  9086. disk", respectively.
  9087.  
  9088. (note)
  9089.        Before presenting the disk initialization dialog,
  9090.        DIBadMount checks whether the drive contains an already
  9091.        mounted volume; if so, it ejects the disk and returns 2
  9092.        as its result. This will happen rarely and may reflect
  9093.        an error in your program (for example, you forgot to call
  9094.        DILoad and the user had to switch to the disk containing
  9095.        the system resource file).
  9096.  
  9097.     If the user responds to the disk initialization dialog by clicking
  9098. the Eject button, DIBadMount ejects the disk and returns 1 as its result
  9099. If the Initialize button is clicked, a box displaying the message
  9100. "Initializing disk..." appears, and DIBadMount attempts to initialize
  9101. the disk. If initialization fails, the disk is ejected and the user is
  9102. informed as shown in Figure D-2; after the user clicks OK, DIBadMount
  9103. returns a negative result code ranging from firstDskErr to lastDskErr,
  9104. indicating that a low-level disk error occurred.
  9105.  
  9106.     If the disk is successfully initialized, the dialog box in Figure D
  9107. appears. After the user names the disk and clicks OK, DIBadMount
  9108. mounts the volume by calling the File Manager function PBMountVol and
  9109. returns PBMountVol's result code (noErr if no error occurs).
  9110.  
  9111.       Result codes
  9112.       ------------
  9113.       noErr                No error
  9114.       extFSErr             External file system
  9115.       mFulErr              Memory full
  9116.       nsDrvErr             No such drive
  9117.       paramErr             Bad drive number
  9118.       volOnLinErr          Volume already on-line
  9119.       firstDskErr          Low-level disk error
  9120.       through lastDskErr
  9121.  
  9122.       Other results
  9123.       -------------
  9124.       1                    User clicked Eject
  9125.       2                    Mounted volume in drive
  9126. \ DIFormat
  9127. 13
  9128. FUNCTION DIFormat (drvNum: INTEGER) : OSErr;
  9129.  
  9130.     DILFormat formats the disk in the drive specified by the given drive
  9131. number and returns a result code indicating whether the formatting was
  9132. completed successfully or failed. Formatting a disk consists of
  9133. writing special infromation onto it so that the Disk Driver can read
  9134. from and write to the disk.
  9135.  
  9136.       Result codes
  9137.       ------------
  9138.       noErr               No error
  9139.       firstDskErr         Low-level disk error
  9140. \ DIVerify
  9141. 13
  9142. FUNCTION DIVerify (drvNum: INTEGER) : OSErr;
  9143.  
  9144.     DIVerify verifies the format of the disk in the drive specified by
  9145. the given drive number; it reads each bit from the disk and returns a
  9146. result code indicating whether all bits were read successfully or not.
  9147.  
  9148.       Result codes
  9149.       ------------
  9150.       noErr                 No error
  9151.       firstDskErr           Low-level disk error
  9152. \ DIZero
  9153. 13
  9154. FUNCTION DIZero (drvNum: INTEGER; volName: Str255) : OSErr;
  9155.  
  9156.     On the unmounted volume in the drive specified by the given drive
  9157. number, DIZero writes the volume information, a block map, and a file
  9158. directory as for a volume with no files; the volName parameter
  9159. specifies the volume name to be included in the volume information.
  9160. This is the last step in initialization (after formatting and
  9161. verifying) and makes any files that are already on the volume
  9162. permanently inaccessible. If the operation fails, DIZero returns a
  9163. result code indicating that a low-level disk error occurred; otherwise,
  9164. it mounts the volume by calling the File Manager function PBMountVol
  9165. and returns PBMountVol's result code (noEr if no error occurs).
  9166.  
  9167.  
  9168.       Result codes
  9169.       ------------
  9170.       noErr                    No error
  9171.       badMDBErr                Bad master directory block
  9172.       extFSErr                 External file system
  9173.       ioErr                    Disk I/O error
  9174.       mFulErr                  Memory full
  9175.       noMacDskErr              Not a Macintosh volume
  9176.       nsDrvErr                 No such drive
  9177.       paramErr                 Bad drive number
  9178.       volOnLinErr              Volume already on-line
  9179.       firstDskErr              Low-level disk error
  9180.       through lastDskErr
  9181. \ InitApplZone
  9182. 14
  9183. PROCEDURE InitApplZone;
  9184.  
  9185.       _________________________________________________________
  9186.  
  9187.       Trap macro            _InitApplZone
  9188.       On exit               D0:  result code (integer)
  9189.  
  9190.       _________________________________________________________
  9191.  
  9192.  
  9193.     InitApplZone initializes the application heap zone and makes it the
  9194. current zone. The contents of any previous application zone are lost;
  9195. all previously existing blocks in that zone are discarded.
  9196. InitApplZone is called by the Segment Loader when starting up an
  9197. application;  you shouldn't normally need to call it.
  9198.  
  9199. (warning)
  9200.        Reinitializing the application zone from within a running
  9201.        program is tricky, since the program's code itself
  9202.        resides in the application zone. To do it safely, the
  9203.        code containing the InitApplZone call cannot be in the
  9204.        application zone.
  9205.  
  9206.     The application zone has an initial size of 6K bytes, and can be
  9207. expanded as needed in 1K increments. Space is initially allocated for
  9208. 64 master pointers; should more be needed later, they will be added 64
  9209. at a time. The zone's grow zone function is set to NIL.
  9210.  
  9211.        Result codes        noErr         No eror
  9212. \ SetApplBase
  9213. 14
  9214. PROCEDURE SetApplBase (startPtr: Ptr);
  9215.  
  9216.             _________________________________________________
  9217.  
  9218.      Trap macro               _SetApplBase
  9219.      On entry                 A0:  startPtr (pointer)
  9220.      On exit                  D0:  result code (integer)
  9221.  
  9222.             _________________________________________________
  9223.  
  9224.  
  9225.     SetApplBase changes the starting address of the application heap
  9226. zone to the address designated by startPtr, and then calls IniApplZone.
  9227. SetApplBase is normally called only by the system itself; you should
  9228. never need to call this procedure.
  9229.  
  9230.     Since the application heap zone begins immediately folowing the end
  9231. of the system zone, changingits starting address has the effect of
  9232. changing the size of the system zone. The system zone can be made
  9233. larger, but never smaller; if startPtr points to an address lower than
  9234. the current end of the system zone, it's ignored and the application
  9235. zone's starting address is left unchanged.
  9236.  
  9237. (warning)
  9238.       Like InitApplZone, SetApplBase is a tricky operation,
  9239.       because the code of the program itself resides in the
  9240.       application heap zone. To do it safely, the code
  9241.       containing the SetApplBase call cannot be in the
  9242.       application zone.
  9243.  
  9244.       Result codes     noErr             No error
  9245. \ InitZone
  9246. 14
  9247. PROCEDURE InitZone (pGrowZone: ProcPtr; cMoreMasters: INTEGER;
  9248.                     limitPtr, startPtr: Ptr);
  9249.  
  9250.  
  9251.        ________________________________________________________
  9252.  
  9253.         Trap macro            _InitZone
  9254.  
  9255.         On entry              A0:  pointer to parameter block
  9256.  
  9257.         Parameter block
  9258.                0      startPtr       pointer
  9259.                4      limitPtr       pointer
  9260.                8      cMoreMasters   integer
  9261.               10      pGrowZone      pointer
  9262.  
  9263.         On exit                D0: result code (integer)
  9264.  
  9265.        ________________________________________________________
  9266.  
  9267.  
  9268.     InitZone creates a new heap zone initializes its header and trailer,
  9269. and makes it the current zone. The startPtr parameter is a pointer to
  9270. the first byte of the new zone; limitPtr points to the first byte of
  9271. the zone trailer. The new zone will occupy memory addresses from
  9272. ORD(startPtr) to ORD(limitPtr)+11.
  9273.  
  9274.     CMoreMasters tells how many master pointers should be allocated at a
  9275. time for the new zone. This number of master pointers are created
  9276. initially; should more be needed later, they will be added in
  9277. increments of this same number. For the system heap zone, this number
  9278. is initially 32; for the application heap zone, it's 64.
  9279.  
  9280.     The pGrowZone parameter is a pointer to the grow zone function for
  9281. the new zone, if any. If you're not defining a grow zone function for
  9282. this zone, pass NIL.
  9283.  
  9284.     The new zone includes a 52-byte header, so its actual usable space
  9285. runs from ORD(startPtr)+52 through ORD(limitPtr)-1. In addition, each
  9286. master pointer occupies four bytes within this usable area. Thus the
  9287. total available space in the zone, in bytes, is initially
  9288.  
  9289.       ORD(limitPtr) - ORD(startPtr) - 52 - 4*cMoreMasters
  9290.  
  9291.     This number must not be less than 0. Note that the amount of
  9292. available space in the zone will decrease as more master pointers are
  9293. allocated.
  9294.  
  9295.       Result codes        noErr                No error
  9296. \ SetApplLimit
  9297. 14
  9298. PROCEDURE SetApplLimit (zoneLimit: Ptr);
  9299.  
  9300.         _________________________________________________
  9301.  
  9302.          Trap macro        _SetApplLimit
  9303.  
  9304.          On entry          A0:  zoneLimit (pointer)
  9305.  
  9306.          On exit           D0:  result code (integer)
  9307.  
  9308.         _________________________________________________
  9309.  
  9310.  
  9311.     SetApplLimit sets the application heap limit, beyond which the
  9312. application heap zone can't be expanded. The actual expansion isn't
  9313. under your program's control, but is done automatically by the Memory
  9314. Manager when necessary to satisfy allocation requests. Only the
  9315. original application zone can be expanded.
  9316.  
  9317.     ZoneLimit  is a limit pointer to a byte in memory beyond which the
  9318. zone will not be allowed to grow. The zone can grow to include the byte
  9319. preceding zoneLimit in memory, but no farther. If the zone already
  9320. extends beyond the specified limit it won't be cut back, but it will be
  9321. prevented from growing any more.
  9322.  
  9323. (warning)
  9324.        Notice that zoneLimit is not a byte count. To limit the
  9325.        application zone to a particular size (say 8Kbytes), you
  9326.        have to write something like
  9327.  
  9328.             SetApplLimit(Ptr(ApplicZone)+8192)
  9329.  
  9330.        The Memory Manager function ApplicZone is explained
  9331.        below.
  9332.  
  9333.  
  9334.             _________________________________________________
  9335.  
  9336.        Assembly-language note:  The global variable ApplLimit contains
  9337.        the application heap limit.
  9338.  
  9339.             _________________________________________________
  9340.  
  9341.  
  9342.        Result codes      noErr           No error
  9343. \ MaxApplZone
  9344. 14
  9345. PROCEDURE MaxApplZone;    [No trap macro]
  9346.  
  9347.     MaxApplZone expands the application heap zone to the application
  9348. heap limit without purging any blocks currently in the zone. If the
  9349. zone already extends to the limit, it won't be changed.
  9350.  
  9351.       Result codes      noErr           No error
  9352. \ MoreMasters
  9353. 14
  9354. PROCEDURE MoreMasters;
  9355.  
  9356.             _________________________________________________
  9357.  
  9358.        Trap macro         _MoreMasters
  9359.  
  9360.             _________________________________________________
  9361.  
  9362.     MoreMasters allocates another block of master pointers in the
  9363. current heap zone. This procedure is usually called very early in an
  9364. application.
  9365.  
  9366.      Result codes
  9367.      ------------
  9368.      noErr             No error
  9369.      memFullErr        Not enough room in zone
  9370. \ GetZone
  9371. 14
  9372. FUNCTION GetZone:  THz;
  9373.  
  9374.             _________________________________________________
  9375.  
  9376.       Trap macro             _GetZone
  9377.  
  9378.       On exit                A0:  function result (pointer)
  9379.                              D0:  result code (integer)
  9380.             _________________________________________________
  9381.  
  9382.     GetZone returns a pointer to the curent heap zone.
  9383.  
  9384.             _________________________________________________
  9385.  
  9386.       Assembly-language note:  The global variable TheZone contains a
  9387.       pointer to the current heap zone.
  9388.             _________________________________________________
  9389.  
  9390.       Result codes      noErr          No error
  9391. \ SetZone
  9392. 14
  9393. PROCEDURE SetZone (hz: THz);
  9394.  
  9395.             _________________________________________________
  9396.  
  9397.        Trap macro      _SetZone
  9398.  
  9399.        On entry        A0:  hz (pointer)
  9400.  
  9401.        On exit         D0:  result code (integer)
  9402.             _________________________________________________
  9403.  
  9404.     SetZone sets the current heap zone to the zone pointed to by hz.
  9405.  
  9406.             _________________________________________________
  9407.  
  9408.        Assembly-language note:  You can set the current heap zone by
  9409.        storing a pointer to it in the global variable TheZone.
  9410.             _________________________________________________
  9411.  
  9412.        Result codes          noErr           No error
  9413.  
  9414.  
  9415.  
  9416. \ SystemZone
  9417. 14
  9418. FUNCTION SystemZone : THz;       [No trap macro]
  9419.  
  9420.     SystemZone returns a pointer to the system heap zone.
  9421.  
  9422.             _________________________________________________
  9423.  
  9424.        Assembly-language note:  The global variable SysZone contains a
  9425.        pointer to the system heap zone.
  9426.             _________________________________________________
  9427.  
  9428.        Result codes            noErr        No error
  9429. \ ApplicZone
  9430. 14
  9431. PROCEDURE ApplicZone : THz;  [No trap macro]
  9432.  
  9433.     ApplicZone returns a pointer to the original application heap zone.
  9434.  
  9435.             _________________________________________________
  9436.  
  9437.      Assembly-language note:  The global variable ApplZone contains a
  9438.      pointer to the original application heap zone.
  9439.             _________________________________________________
  9440.  
  9441.      Result codes         noErr          No error
  9442. \ NewHandle
  9443. 14
  9444. FUNCTION NewHandle (logicalSize: Size) : Handle;
  9445.  
  9446.     __________________________________________________________
  9447.  
  9448. Trap macro       _NewHandle
  9449.                  _NewHandle ,SYS           (applies to system heap)
  9450.                  _NewHandle ,CLEAR         (clears allocated block)
  9451.                  _NewHandle ,SYS,CLEAR     (applies to system heap and
  9452.                                             clears allocated block)
  9453.  
  9454. On entry         D0:  logicalSize (long integer)
  9455.  
  9456. On exit          A0:  function result (handle)
  9457.                  D0:  result code (integer)
  9458.     __________________________________________________________
  9459.  
  9460.     NewHandle attempts to allocate a new relocatable block of
  9461. logicalSize bytes from the current heap zone and then return a handle to
  9462. it. The new block will be unlocked and unpurgeable. If logicalSize bytes
  9463. can't be allocated, NewHandle returns NIL.
  9464.  
  9465.     NewHandle will pursue all available avenues to create a free block
  9466. of the requested size, includinig compacting the heap zone, increasing
  9467. its size, purging blocks from it, and calling its grow zone function, if
  9468. any.
  9469.  
  9470.        Result codes     noErr           No error
  9471.                         memFulErr       Not enough room in zone
  9472. \ DisposHandle
  9473. 14
  9474. PROCEDURE DisposHandle (h: Handle);
  9475.  
  9476.             _________________________________________________
  9477.  
  9478.       Trap macro           _DisposHandle
  9479.  
  9480.       On entry             A0:  h (handle
  9481.  
  9482.       On exit              A0:  0
  9483.                            D0: result code (integer)
  9484.             _________________________________________________
  9485.  
  9486.     DisposHandle releases the memory occupied by the relocatable block
  9487. whose handle is h.
  9488.  
  9489. (warning)
  9490.        After a call to DisposHandle, all handles to the released
  9491.        block become invalid and should not be used again.
  9492.  
  9493.        Result codes     noErr       No error
  9494.                         memWZErr    Attempt to operate on a free block
  9495. \ GetHandleSize
  9496. 14
  9497. FUNCTION GetHandleSize (h: Handle) : Size;
  9498.  
  9499.             _________________________________________________
  9500.  
  9501.      Trap macro      _GetHandleSize
  9502.  
  9503.      On entry        A0:  h (handle)
  9504.  
  9505.      On exit         D0:  if >=0, function result (long integer)
  9506.                           if <0, result code (integer)
  9507.             _________________________________________________
  9508.  
  9509.     GetHandleSize returns the logical size, in bytes, of the relocatable
  9510. block whose handle is h. In case of an error, GetHandleSize returns 0.
  9511.  
  9512.             _________________________________________________
  9513.  
  9514.      Assembly-language note:  Recall that the trap dispatcher sets
  9515.      the condition codes before returning from a trap by testing the
  9516.      low-order word of register D0 with a TST.W instruction. Since
  9517.      the block size returned in D0 by _GetHandleSize is a full 32-bit
  9518.      long word, the word-length test sets the condition codes
  9519.      incorrectly in this case. To branch on the contents of D0, use
  9520.      your own TST.L instruction on return from the trap to test the
  9521.      full 32 bits of the register.
  9522.             _________________________________________________
  9523.  
  9524.      Result codes    noErr           No error   [Pascal only]
  9525.                     nilHandleErr     NIL master pointer
  9526.                     memWZErr         Attempt to operate on a free block
  9527. \ SetHandleSize
  9528. 14
  9529. PROCEDURE SetHandleSize (h: Handle; newSize: Size);
  9530.  
  9531.             _________________________________________________
  9532.  
  9533.      Trap macro          _SetHandleSize
  9534.  
  9535.      On entry       A0:  h (handle)
  9536.                     D0:  newSize (long integer)
  9537.  
  9538.      On exit        D0:  result code (integer)
  9539.             _________________________________________________
  9540.  
  9541.     SetHandleSize changes the logical size of the relocatable block
  9542. whose handle is h to newSize bytes.
  9543.  
  9544. (note)
  9545.        Don't attempt to increase the size of a locked block,
  9546.        becausse its unlikely the Memory Manager will be able to
  9547.        do so.
  9548.  
  9549.        Result codes
  9550.  
  9551.        noErr         No error
  9552.        memFullErr    Not enough room to grow
  9553.        nilHandleErr  NIL master pointer
  9554.        memWZErr      Attempt to operate on a free block
  9555. \ HandleZone
  9556. 14
  9557. FUNCTION HandleZone (h: Handle) : THz;
  9558.  
  9559.         _________________________________________________
  9560.  
  9561.           Trap macro    _HandleZone
  9562.  
  9563.           On entry      A0: h (handle)
  9564.  
  9565.           On exit       A0:  function result (pointer)
  9566.                         D0:  result code (integer)
  9567.         _________________________________________________
  9568.  
  9569.     HandleZone returns a pointer to the heap zone containing the
  9570. relocatable block whose handle is h.
  9571.  
  9572. (warning)
  9573.         If handle h is empty (points to a NIL master pointer),
  9574.     HandleZone returns a pointer to the current heap zone.
  9575.     In case of an error, the result returned by HandleZone is
  9576.     meaningless and should be ignored.
  9577.  
  9578. Result codes      noErr            No error
  9579.                   memWZErr         Attempt to operate on a free block
  9580. \ RecoverHandle
  9581. 14
  9582. FUNCTION RecoverHandle (p:Ptr) : Handle;
  9583.  
  9584.             _________________________________________________
  9585.  
  9586.       Trap macro      _RecoverHandle
  9587.                       _RecoverHandle ,SYS     (applies to system heap)
  9588.  
  9589.       On entry        A0:  p (pointer)
  9590.  
  9591.       On exit         A0:  function result (handle)
  9592.                       D0:  unchanged
  9593.             _________________________________________________
  9594.  
  9595.  
  9596.     RecoverHandle returns a handle to the relocataable block pointed to
  9597. by p.
  9598.  
  9599.             _________________________________________________
  9600.  
  9601.     Assembly-language note:  The trap _RecoverHandle doesn't return
  9602.     a result code in register D0; the previous contents of D0 are
  9603.     preserved unchanged.
  9604.             _________________________________________________
  9605.  
  9606.     Result codes     noErr          No error   [Pascal only]
  9607. \ ReallocHandle
  9608. 14
  9609. PROCEDURE ReallocHandle (h: Handle; logicalSize: Size);
  9610.  
  9611.             _________________________________________________
  9612.  
  9613.     Trap macro         _ReallocHandle
  9614.  
  9615.     On entry           A0:  h (handle)
  9616.                        D0:  logicalSize   (integer)
  9617.  
  9618.     On exit            A0:  original h or 0
  9619.                        D0:  result code  (integer)
  9620.             _________________________________________________
  9621.  
  9622.     ReallocHandle allocates a new relocatable block with a logical size
  9623. of logicalSize bytes. It then updates handle h by setting its master
  9624. pointer to point to the new block. The main use of this procedure is
  9625. to reallocate space for a block that has been purged. Normally h is an
  9626. empty handle, but it need not be:  if it points to an existing block,
  9627. that block is released before the new block is created.
  9628.  
  9629.     In case of an error, no new block is allocated and handle h is left
  9630. unchanged.
  9631.  
  9632.             _________________________________________________
  9633.  
  9634.     Assembly-language note:  On return from ReallocHandle, register
  9635.     A0 contains the original handle h, or 0 if no room could be
  9636.     found for the requested block.
  9637.             _________________________________________________
  9638.  
  9639.     Result codes
  9640.  
  9641.             noErr       Noerror
  9642.             memFullErr  Not enough room in zone
  9643.             memWZErr    Attempt to operate on a free block
  9644.             MemPurErr   Block is locked
  9645. \ NewPtr
  9646. 14
  9647. FUNCTION NewPtr (logicalSize: Size) : Ptr;
  9648.  
  9649.             _________________________________________________
  9650.  
  9651.     Trap macro  _NewPtr
  9652.                 _NewPtr ,SYS        (applies to system heap)
  9653.                 _NewPtr ,CLEAR      (clears allocated block)
  9654.                 _NewPtr ,SYS,CLEAR  (applies to system heap and
  9655.                                     clears allocated block)
  9656.  
  9657.     On entry    D0:  logicalSize (long integer)
  9658.  
  9659.     On exit     A0:  function result (pointer)
  9660.                 D0:  result code (integer)
  9661.             _________________________________________________
  9662.  
  9663.     NewPtr attempts to allocate a new nonrelocatable block of
  9664. logicalSize bytes from the current heap zone and then return a pointer
  9665. to it. If logicalSize bytes can't be allocated, NewPtr returns NIL.
  9666.  
  9667.     Newptr will pursue all available avenues to create a free block of
  9668. the requested size, including compacting the heap zone, increasing its
  9669. size, purging blocks from it, and calling its grow zone function, if
  9670. any.
  9671.  
  9672.     Result codes
  9673.  
  9674.             noErr       No error
  9675.             memFullErr  Not enough room in zone
  9676. \ DisposPtr
  9677. 14
  9678. PROCEDURE DisposPtr (p: Ptr);
  9679.  
  9680.           _________________________________________________
  9681.  
  9682.             Trap macro  _DisposPtr
  9683.  
  9684.             On entry    A0:  p (pointer)
  9685.  
  9686.             On exit     A0:  0
  9687.                         D0:  result code (integer)
  9688.           _________________________________________________
  9689.  
  9690.     DisposPtr releases the memory occupied by the nonrelocatable block
  9691. pointed to by p.
  9692.  
  9693. (warning)
  9694.     After a call to DisposPtr, all pointers to the released
  9695.     block become invalid and should not be used again.
  9696.  
  9697.     Result codes
  9698.  
  9699.             noErr       No error
  9700.             memWZErr    Attempt to operated on a free block
  9701. \ GetPtrSize
  9702. 14
  9703. FUNCTION GetPtrSize (p: Ptr) : Size;
  9704.  
  9705.     ___________________________________________________________
  9706.  
  9707.     Trap macro  _GetPtrSize
  9708.  
  9709.     On entry    A0:  p (pointer)
  9710.  
  9711.     On exit     D0:  if >=0, function result (long integer)
  9712.                      if <0, result code (integer)
  9713.     ___________________________________________________________
  9714.  
  9715.     GetPtrSize returns the logical size, in bytes, of the nonrelocatable
  9716. block pointed to by p. In case of an error, GetPtrSize returns 0.
  9717.  
  9718.     ___________________________________________________________
  9719.  
  9720.     Assembly-language note:  Recall that the trap dispatcher sets
  9721.     the condition codes before returning from a trap by testing the
  9722.     low-order half of register D0 with a TST.W instruction. Since
  9723.     the block size returned in D0 by _GetPtrSize is a full 32-bit
  9724.     long word, the word-length test sets the condition codes
  9725.     incorrectly in this case. To branch on the contents of D0, use
  9726.     your own TST.L instruction on return from the trap to test the
  9727.     full 32 bits of the register.
  9728.     ___________________________________________________________
  9729.  
  9730.     Result codes
  9731.  
  9732.             noErr       No error   [Pascal only]
  9733.             memWZErr    Attempt to operate on a free block
  9734. \ SetPtrSize
  9735. 14
  9736. PROCEDURE SetPtrSize (p: Ptr; newSize: Size);
  9737.  
  9738.     ___________________________________________________________
  9739.  
  9740.     Trap macro  _SetPtrSize
  9741.  
  9742.     On entry    A0:  p (pointer)
  9743.  
  9744.     On exit     A0:  function result (pointer)
  9745.             D0:  result code (integer)
  9746.     ___________________________________________________________
  9747.  
  9748.     PtrZone returns a pointer to the heap zone containing the
  9749. nonrelocatable block pointed to by p. In case of an error, the result
  9750. returned by PtrZone is meaningless and should be ignored.
  9751.  
  9752.     Result codes
  9753.  
  9754.             noErr       No error
  9755.             memWZErr    Attempt to operate on a free block
  9756. \ FreeMem
  9757. 14
  9758. FUNCTION FreeMem : LONGINT;
  9759.  
  9760.         _______________________________________________________
  9761.  
  9762.         Trap macro  _FreeMem
  9763.                     _FreeMem ,SYS   (applies to system heap
  9764.  
  9765.         On exit     D0:  function result (long integer)
  9766.         _______________________________________________________
  9767.  
  9768.     FreeMem returns the total amount of free space in the current heap
  9769. zone, in bytes. Notice that it ususally isn't possible to allocate a 
  9770. block of this size, because of fragmentation due to nonrelocatable or
  9771. locked blocks.
  9772.  
  9773.     Result codes
  9774.  
  9775.             noErr   No error
  9776. \ MaxMem
  9777. 14
  9778. FUNCTION MaxMem (VAR grow: Size) : Size;
  9779.  
  9780.             _________________________________________________
  9781.  
  9782.     Trap macro  _MaxMem
  9783.                 _MaxMem ,SYS            (applies to system heap)
  9784.  
  9785.     On exit     D0:  function result    (long integer)
  9786.                 A0:  grow               (long integer)
  9787.             _________________________________________________
  9788.  
  9789.     MaxMem compacts the current heap zone and purges all purgeable
  9790. blocks from the zone. It returns as its result the size in bytes of the
  9791. largest contiguous free block in the zone after the compaction. If the
  9792. current zone is the original application heap zone, the variable
  9793. parameter grow is set to the maximum number of bytes by which the zone
  9794. can grow. For any other heap zone, grow is set to 0. MaxMem doesn't
  9795. actually expand the zone or call its grow zone function.
  9796.  
  9797.     Result codes
  9798.  
  9799.             noErr   No error
  9800. \ CompactMem
  9801. 14
  9802. FUNCTION CompactMem (cbNeeded: Size) : Size;
  9803.  
  9804.     ___________________________________________________________
  9805.  
  9806.     Trap macro  _CompactMem
  9807.                 _CompactMem ,SYS    (applies to system heap)
  9808.  
  9809.     On entry    D0:  cbNeeded (longinteger)
  9810.  
  9811.     On exit     D0:  function result (long integer)
  9812.     ___________________________________________________________
  9813.  
  9814.     CompactMem compacts the current heap zone by moving relocatable
  9815. blocks forward and collecting free space together until a contiguous
  9816. block of at least cbNeeded free bytes is found or the entire zone is
  9817. compacted; it doesn't purge any purgeable blocks. CompactMem returns
  9818. the size in bytes of the largest contiguous free block remaining. Note
  9819. that it doesn't actually allocate the block.
  9820.  
  9821. (notee)
  9822.     To force a compaction of the entire heap zone, pass
  9823.     maxSize for cbNeeded.
  9824.  
  9825.     Result codes
  9826.  
  9827.         noErr       No error
  9828. \ ResrvMem
  9829. 14
  9830. FUNCTION ResrvMem (cbNeeded: Size);
  9831.  
  9832.     ___________________________________________________________
  9833.  
  9834.     Trap macro  _ResrvMem
  9835.                 _ResrvMem ,SYS      (applies to system heap)
  9836.  
  9837.     On entry    D0:  cbNeeded (long integer)
  9838.  
  9839.     On exit     D0:  result code  (integer)
  9840.     ___________________________________________________________
  9841.  
  9842.     ResrvMem creates free space for a block of cbNeeded contiguous bytes
  9843. at the lowest possible position in the current heap zone. It will try
  9844. every available means to place the block as close as possible to the
  9845. beginnig of the zone, including moving other blocks upward, expanding
  9846. the zone, or purging blocks from it. Notice that ResrvMem doesn't
  9847. actually allocate the block.
  9848.  
  9849. (note)
  9850.     When you allocate a relocatable block that you know will
  9851.     be locked for long periods of time, call ResrvMem first.
  9852.     This reserves space for the block near the beginning of
  9853.     the heap zone, where it will interfere with compaction as
  9854.     little as possible. It isn't necessary to call ResrvMem
  9855.     for a nonrelocatable block; NewPtr calls it
  9856.     automatically.
  9857.  
  9858.     Result codes
  9859.  
  9860.             noErr       No error
  9861.             memFullErr  Not enough room in zone
  9862. \ PurgeMem
  9863. 14
  9864. PROCEDURE PurgeMem (cbNeeded: Size);
  9865.  
  9866.     ___________________________________________________________
  9867.  
  9868.     Trap macro  _PurgeMem
  9869.                 _PurgeMEM ,SYS  (applies to system heap)
  9870.  
  9871.     On entry    D0:  cbNeeded (long integer)
  9872.  
  9873.     On exit     D0:  result code (integer)
  9874.     ___________________________________________________________
  9875.  
  9876.     PurgeMem sequentially purges blocks from the current heap zone until
  9877. a contiguous block of at least cbNeeded free bytes is created or the
  9878. entire zone is purged; it doesn't compact the heap zone. Only
  9879. relocatable, unlocked, purgeable blocks can be purged. Notice that
  9880. PurgeMem doesn't actually allocate the block.
  9881.  
  9882. (note)
  9883.     To force a purge of the entire heap zone, pass maxSize
  9884.     for cbNeeded.
  9885.  
  9886.     Result codes
  9887.  
  9888.             noErr       No error
  9889.             memFullErr  Not enough room in zone
  9890. \ EmptyHandle
  9891. 14
  9892. PROCEDURE EmptyHandle (h: Handle);
  9893.  
  9894.     ___________________________________________________________
  9895.  
  9896.     TRap macro  _EmptyHandle
  9897.  
  9898.     On entry    A0:  h (handle)
  9899.  
  9900.     On exit     A0:  h (handle)
  9901.                 D0:  result code (integer)
  9902.     ___________________________________________________________
  9903.  
  9904.     EmptyHandle purges the relocatable block whose handle is h from its
  9905. heap zone and sets its master pointer to NIL (making it an empty
  9906. handle). If h is already empty, EmptyHandle does nothing.
  9907.  
  9908. (note)
  9909.     Since the space occupied by the block's master pointer
  9910.     itself remains allocated, all handles pointing to it
  9911.     remain valid but empty. When you later reallocate space
  9912.     for the block with ReallocHandle, the master pointer will
  9913.     be updated, causing all existing handles to point
  9914.     correctly to the new block.
  9915.  
  9916.     The block whose handle is h must be unlocked, but need not be
  9917. purgeable.
  9918.  
  9919.     Result codes
  9920.  
  9921.             noErr       No error
  9922.             memWZErr    Attempt to operate on a free block
  9923.             memPurErr   Block is locked
  9924. \ HLock
  9925. 14
  9926. PROCEDURE HLock (h: Handle);
  9927.  
  9928.     ___________________________________________________________
  9929.  
  9930.     Trap macro  _HLock
  9931.  
  9932.     On entry    A0:  h (handle)
  9933.  
  9934.     On exit     D0:  result code (integer)
  9935.     ___________________________________________________________
  9936.  
  9937.     HLock locks a relocatable block, preventing it from being moved
  9938. within its heap zone. If the block is already locked, HLock does
  9939. nothing.
  9940.  
  9941.     ___________________________________________________________
  9942.  
  9943.     Assembly-language note:  Changing the value of the block's
  9944.     master pointer's lock bit with a BSET instruction is faster than
  9945.     HLock. However, HLock may eventually perform additional tasks.
  9946.     ___________________________________________________________
  9947.  
  9948.     Result codes
  9949.  
  9950.             noErr       No error
  9951.             nilHandleErr    NIL master pointer
  9952.             memWZErr    Attempt to opetate on a free block
  9953. \ HUnlock
  9954. 14
  9955. PROCEDURE HUnlock (h: Handle);
  9956.  
  9957.     ___________________________________________________________
  9958.  
  9959.     Trap macro  _HUnlock
  9960.  
  9961.     On entry    A0:  h (handle)
  9962.  
  9963.     On exit     D0:  result code (integer)
  9964.     ___________________________________________________________
  9965.  
  9966.     HUnlock unlocks a relocatable block, allowing it to be moved within
  9967. its heap zone. If the block is already unlocked, HUnlock does nothing.
  9968.  
  9969.     ___________________________________________________________
  9970.  
  9971.     Assembly-language note:  Changing the value of the block's
  9972.     master pointer's lock bit with a BCLR instruction is faster than
  9973.     HUnlock. However, HUnlock may eventually perform additional
  9974.     tasks.
  9975.     ___________________________________________________________
  9976.  
  9977.     Result codes
  9978.  
  9979.             noErr           No error
  9980.             nilHandleErr    NIL master pointer
  9981.             memWZErr        Attempt to operate on a fre block
  9982. \ HPurge
  9983. 14
  9984. PROCEDURE HPurge (h: Handle);
  9985.  
  9986.     ___________________________________________________________
  9987.  
  9988.     Trap macro  _HPurge
  9989.  
  9990.     On entry    A0:  h (handle)
  9991.  
  9992.     On exit     D0:  result code (integer)
  9993.     ___________________________________________________________
  9994.  
  9995.     HPurge marks a relocatable block as purgeable. If the block is
  9996. already purgeable, HPurge does nothing.
  9997.  
  9998.     Result codes
  9999.  
  10000.             noErr       No error
  10001.             nilHandleErr    NIL master pointer
  10002.             memWZErr    Attempt to operate on a free block
  10003. \ HNoPurge
  10004. 14
  10005. PROCEDURE HNoPurge (h: Handle);
  10006.  
  10007.     ___________________________________________________________
  10008.     Trap macro  _HNoPurge
  10009.  
  10010.     On entry    A0:  h (handle)
  10011.  
  10012.     On exit     D0:  result code (integer)
  10013.     ___________________________________________________________
  10014.  
  10015.     HNoPurge marks a relocatable block as unpurgeable. If the block is
  10016. already unprugeable, HNoPurge does nothing.
  10017.  
  10018.     Result codes
  10019.  
  10020.             noErr           No error
  10021.             nilHandleErr    NIL master pointerr
  10022.             memWZErr        Attempt to operate on a free block
  10023. \ SetGrowZone
  10024. 14
  10025. PROCEDURE SetGrowZone (growZone: ProcPtr);
  10026.  
  10027.     ___________________________________________________________
  10028.  
  10029.     Trap macro  _SetGrowZone
  10030.  
  10031.     On entry    A0:  growZone (pointer)
  10032.  
  10033.     On exit     D0:  result code (integer)
  10034.     ___________________________________________________________
  10035.  
  10036.     SetGrowZone sets the current heap fzone's grow zone function as
  10037. designated by the growZone parameter. A NIL parameter value removes
  10038. any grow zone function the zone may previously have had.
  10039.  
  10040. (note)
  10041.     If yokur program presses the limits of the available heap
  10042.     space, it's a good idea to have a grow zone function of
  10043.     some sort. At the very least, the grow zone function
  10044.     should detect when the Memory Manager is about to run out
  10045.     of space at a critical time (see GZCritical, below) and
  10046.     take some graceful action--such as displaying an alert
  10047.     box with the message "Out of memory"--instead of just
  10048.     failing unpredictably.
  10049.  
  10050.     The Memory Manager calls the grow zone function as a last resort
  10051. when trying to allocate space, if it has failed to create a block of the
  10052. needed size after compacting the zone, increasing its size (in the case
  10053. of the origianal application zone), or purging blocks from it. Memory
  10054. Manager routines that may cause the grow zone function to be called are
  10055. NewHandle, NewPtr, SetHandleSize, SetPtrSize, ReallocHandle, and
  10056. ResrvMem.
  10057.  
  10058. The grow zone function should be of the form
  10059.  
  10060.     FUNCTION MyGrowZone (cbNeeded: Size) : Size;
  10061.  
  10062.     The cbNeeded parameter gives the physical size of the needed block
  10063. in bytes, including the block header. The grow zone function should
  10064. attempt to create a free block of at least this size. It should return
  10065. a nonzero number if it's abale to allocate some memory, or 0 if it's not
  10066. able to allocate any.
  10067.  
  10068.     If the grow zone function returns 0, the Memory Manager will give up
  10069. trying to allocate the needed block and will signal failure with the
  10070. result code memFullErr. Otherwise it will compact the heap zone and
  10071. try again to allocate the block. If still unsuccessful, it will
  10072. continue to call the grow zone function repeatedly, compacting the zone
  10073. again after each call, until it either succeeds in allocating the
  10074. needed block or receives a zero result and gives up.
  10075.  
  10076.     The usual way for the grow zone function to free more space is to
  10077. call EmptyHandle to purge blocks that were previously marked
  10078. unpurgeable. Another possibility is to unlock blocks that were
  10079. previously locked.
  10080.  
  10081. (note)
  10082.     Although just unlocking blocks doesn't actually free any
  10083.     additional space in the zone, the grow zone function
  10084.     should still return a nonzero result in this case. This
  10085.     signals the Memory Manager to compact the heap and try
  10086.     again to allocate the needed block.
  10087.  
  10088. (warning)
  10089.     Depending on the circumstances in which the grow zone
  10090.     function is called, there may be particular blocks within
  10091.     the heap zone that must not be purged or released. For
  10092.     instance, if your program is attempting to increase the
  10093.     size of a relocatable block with SetHandleSize, it would
  10094.     be disastrous to release the block being expanded. To
  10095.     deal with such cases safely, it's essential to understand
  10096.     the use of the functions GZCritical and GZSaveHnd (see
  10097.     below).
  10098.  
  10099. (warning)
  10100.     Whenever you call the Resource Manager with
  10101.     SetResPurge(TRUE), it installs its own grow zone function
  10102.     into the application heap zone. The Resource Manager's
  10103.     grow zone function automatically writes to the disk all
  10104.     changed resources before they're purged. If you install
  10105.     your own grow zone function into the application heap
  10106.     zone, you shouldn't call SetResPurge(TRUE).
  10107.  
  10108.     Result codes
  10109.  
  10110.             noErr   No error
  10111. \ GZCritical
  10112. 14
  10113. FUNCTION GZCritical : BOOLEAN;    [No trap macro]
  10114.  
  10115.     GZCritical retruns TRUE if the Memory Manager critically needs
  10116. space-- for example, to create a new relocatable or nonrelocatable block
  10117. or to reallocate a handle. It returns FALSE in less critical cases,
  10118. such as ResrvMem trying to reserve space as low as possible in the heap
  10119. zone or SetHandleSize trying to increase the size of a relocatable
  10120. block. GZCritical doesn't affect the value returned by MemError.
  10121.  
  10122. (warning)
  10123.     If you're writing a grow zone function in Pascal, you
  10124.     should always call GZCritical and proceed only if the
  10125.     result is TRUE. All the information you need to handle
  10126.     the critical cases safely is the value of GZSaveHnd (see
  10127.     below). The noncritical cases require additional
  10128.     information that isn't available from Pascal, so your
  10129.     grow zone function should just return 0 and not attempt
  10130.     to free any space.
  10131. \ GZSaveHnd
  10132. 14
  10133. FUNCTION GZSaveHnd : Handle;   [No trap macro]
  10134.  
  10135.     GZSave Hnd retruns a handle to a relocatable block that mustn't be
  10136. purged or released by the grow zone function, or NIL if there is no
  10137. such block. For example, during a SetHandleSize call, the handle being
  10138. changed mustn't be purged. The grow zone function will be safe if it
  10139. avoids purging or releasing this block, provided that the grow zone
  10140. call was critical. To handle noncritical cases safely, further
  10141. information is needed that isn't available from Pascal. GZSaveHnd
  10142. doesn't affect the value returned by MemError.
  10143. \ BlockMove
  10144. 14
  10145. PROCEDURE BlockMove (sourcePtr,destPtr: Ptr; byteCount: Size);
  10146.  
  10147.  
  10148.     ___________________________________________________________
  10149.  
  10150.     Trap macro  _BlockMove
  10151.  
  10152.     On entry    A0:  sourcePtr (pointer)
  10153.                 A1:  destPtr (pointer)
  10154.                 D0:  byteCount (long integer)
  10155.  
  10156.     On exit     D0:  result code (integer)
  10157.     ___________________________________________________________
  10158.  
  10159.     BlockMove moves a block of byteCount consecutive bytes from the
  10160. address designated by sourcePtr to that designated by destPtr. No
  10161. pointers are updated.
  10162.  
  10163.     Result codes
  10164.  
  10165.             noErr   No error
  10166. \ TopMem
  10167. 14
  10168. FUNCTION TopMem : Ptr;   [No trap macro]
  10169.  
  10170.     TopMem returns a pointer to the address following the last byte of
  10171. RAM.
  10172.  
  10173.             _________________________________________________
  10174.  
  10175.     Assembly-language note:  To get a pointer to the end of RAM from
  10176.     assembly language, use the global variable MemTop.
  10177.             _________________________________________________
  10178.  
  10179.     Result codes
  10180.  
  10181.             noErr   No error
  10182. \ MemError
  10183. 14
  10184. FUNCTION MemError : OSErr;   [No trap macro]
  10185.  
  10186.     MemError returns the result code produced by the last Memory Manager
  10187. routine called. (OSErr is an Operating System Utility data type
  10188. declared as INTEGER.)
  10189. \MaxBlock
  10190. 14
  10191. FUNCTION MaxBlock : LONGINT;
  10192.     ______________________________________________________________
  10193.  
  10194.     Trap macro  _MaxBlock
  10195.                 _MaxBlock ,SYS  (applies to system heap)
  10196.  
  10197.     On exit     D0:  function result (word)
  10198.     ______________________________________________________________
  10199.     MaxBlock returns the maximum contiguous space in bytes that could be
  10200. obtained by compacting the current zone (without actually doing
  10201. the compaction).
  10202. \PurgeSpace
  10203. 14
  10204. PROCEDURE PurgeSpace (VAR total,contig: LONGINT);
  10205.     ______________________________________________________________
  10206.  
  10207.     Trap macro  _PurgeSpace
  10208.                 _PurgeSpace ,SYS    (applies to system heap)
  10209.  
  10210.     On exit     A0:  contig (long word)
  10211.                 D0:  total (long word)
  10212.     ______________________________________________________________
  10213.     PurgeSpace returns in total the total amount of space in bytes that
  10214. could be obtained by a general purge (without actually doing
  10215. the purge); this amount includes space that is already free.
  10216. The maximum contiguous space in bytes (including already free space)
  10217. that could be obtained by a purge is returned in contig.
  10218. \StackSpace
  10219. 14
  10220. FUNCTION StackSpace : LONGINT;
  10221.     ______________________________________________________________
  10222.  
  10223.     Trap macro  _StackSpace
  10224.  
  10225.     On exit     D0:  function result (word)
  10226.     ______________________________________________________________
  10227.     StackSpace returns the current amount of stack space between the
  10228. current stack pointer and the application heap (at the instant
  10229. of return from the trap).
  10230. \NewEmptyHandle
  10231. 14
  10232. FUNCTION NewEmptyHandle : Handle;
  10233.     ______________________________________________________________
  10234.  
  10235.     Trap macro  _NewEmptyHandle
  10236.                 _NewEmptyHandle ,SYS    (applies to system heap)
  10237.  
  10238.     On exit     A0:  function result (handle)
  10239.                 D0:  result code (word)
  10240.     ______________________________________________________________
  10241.  
  10242.     NewEmptyHandle is similar in function to NewHandle except that it
  10243. does not allocate any space; the handle returned is empty (in
  10244. other words, it points to a NIL master pointer). NewEmptyHandle
  10245. is used extensively by the Resource Manager; you may not need to use it.
  10246. \HSetRBit
  10247. 14
  10248. PROCEDURE HSetRBit (h: Handle);
  10249.     ______________________________________________________________
  10250.  
  10251.     Trap macro  _HSetRBit
  10252.  
  10253.     On entry    A0:  h (handle)
  10254.  
  10255.     On exit     D0:  result code (word)
  10256.     ______________________________________________________________
  10257.  
  10258.     HSetRBit sets the resource flag of a relocatable block’s master
  10259. pointer.
  10260. \HClrRBit
  10261. 14
  10262. PROCEDURE HClrRBit (h: Handle);
  10263.     ______________________________________________________________
  10264.  
  10265.     Trap macro  _HClrRBit
  10266.  
  10267.     On entry    A0:  h (handle)
  10268.  
  10269.     On exit     D0:  result code (word)
  10270.     ______________________________________________________________
  10271.     HClrRBit clears the resource flag of a relocatable block’s master
  10272. pointer.
  10273. \HGetState
  10274. 14
  10275. FUNCTION HGetState (h: Handle) : SignedByte;
  10276.     ______________________________________________________________
  10277.  
  10278.     Trap macro  _HGetState
  10279.  
  10280.     On entry    A0:  h (handle)
  10281.  
  10282.     On exit     D0:  flags (byte)
  10283.     ______________________________________________________________
  10284.     HGetState returns the byte that contains the flags of the master
  10285. pointer for the given handle; it’s used in conjunction with HSetState
  10286. to save and restore the state of the flags contained in this byte.
  10287. You can save this byte, change the state of any of the flags (using
  10288. the routines described above), and then restore their original state
  10289. by passing the byte back to the HSetState procedure (described below).
  10290. \HSetState
  10291. 14
  10292. PROCEDURE HSetState (h: Handle; flags: SignedByte);
  10293.     ______________________________________________________________
  10294.  
  10295.     Trap macro  _HSetState
  10296.  
  10297.     On entry    A0:  h (handle)
  10298.                 D0:  flags (byte)
  10299.  
  10300.     On exit     D0:  result code (word)
  10301.     ______________________________________________________________
  10302.  
  10303.     HSetState is used in conjunction with HGetState; it sets the byte
  10304. that contains the flags of the master pointer for the given handle
  10305. to the byte specified by flags.
  10306. \ UnloadSeg
  10307. 15
  10308. PROCEDURE UnloadSeg (routineAddr: Ptr);
  10309.  
  10310.     UnloadSeg unloads a segment, making it relocatable and purgeable;
  10311. routineAddr is the address of any externally referenced routine in the
  10312. segment. The segment won't actually be purged until the memory it
  10313. occupies is needed. If the segment is purged, the Segment Loader will
  10314. reload it the next time one of the routines in it is called.
  10315. \ CountAppFiles
  10316. 15
  10317. PROCEDURE COuntAppFiles (VAR message:  INTEGER; VAR count: INTEGER);
  10318.  
  10319.     CountAppFiles deciphers the Finder information passed to your
  10320. application, and returns information about the documents that were
  10321. selected when your application was started up. It returns the number
  10322. of selected documents in the count parameter, and a number in the
  10323. message parameter that indicates whether the documents are to be opened
  10324. or printed:
  10325.  
  10326.     CONST appOpen  = 0;   {open the document(s)}
  10327.           appPrint = 1;   {print the document(s)}
  10328. \ GetAppFiles
  10329. 15
  10330. PROCEDURE GetAppFiles (index: INTEGER; VAR theFile: AppFile);
  10331.  
  10332.     GetAppFiles returns information about a document that was selected
  10333. when your application was started up (as listed in the Finder
  10334. information). The index parameter indicates the file for which
  10335. information should be returned; it must be between 1 and the number
  10336. returned by CountAppFiles, inclusive. The information is returned in
  10337. the following data structure:
  10338.  
  10339.     TYPE AppFile = RECORD
  10340.             vRefNum: INTEGER;  {volume reference number}
  10341.             fType:   OSType;   {file type}
  10342.             versNum: INTEGER;  {version number}
  10343.             fName:   Str255;   {file name}
  10344.           END;
  10345.  
  10346.     Volume reference number, file type, version number, and file name
  10347. are discussed in the File Manager manual.
  10348. \ ClrAppFiles
  10349. 15
  10350. PROCEDURE ClrAppFiles (index: INTEGER);
  10351.  
  10352.     ClrAppFiles changes the Finder information passed to your aplication
  10353. about the specified file such that the Finder knows you've processed
  10354. the file. The index parameter must be between 1 and the number
  10355. returned by CountAppFiles, inclusive. You should call ClrAppFiles for
  10356. every document your application opens or prints, so that the
  10357. information returned by CountAppFiles and GetAppFiles is always
  10358. correct. (ClrAppFiles sets the file type in the Finder information to
  10359. 0.)
  10360. \ GetAppParms
  10361. 15
  10362. PROCEDURE GetAppParms (VAR apName: STRING[31]; VAR apRefNum: INTEGER;
  10363.         VAR apParam: Handle);
  10364.  
  10365.     GetAppParms returns information about the current application. It
  10366. returns the application name in apName and the reference number for the
  10367. application's resource file in apRefNum. A handle to the Finder
  10368. information is returned in apParam, but the Finder information is more
  10369. easily accessed with the GetAppFiles call.
  10370. \ ExitToShell
  10371. 15
  10372. PROCEDURE ExitToShell;
  10373.  
  10374.     ExitToShell provides an exit from an application by starting up the
  10375. Finder (after releasing the entire application heap).
  10376. \ GetOSEvent
  10377. 16
  10378. FUNCTION GetOSEvent (eventMask: INTEGER; VAR theEvent: EventRecord) :
  10379.                         BOOLEAN;
  10380.  
  10381.     ____________________________________________________________
  10382.  
  10383.     Trap macro  _GetOSEvent
  10384.  
  10385.     On entry    A0:  pointer to event record theEvent
  10386.                 D0:  eventMask (word)
  10387.  
  10388.     On exit     D0:  0 if non-null event returned, or
  10389.                  -1 if null event returned (byte)
  10390.     ____________________________________________________________
  10391.  
  10392.     GEtOSEvent returns the next available event of a specified type or
  10393. types and removes it from the event queue. The event is returned as
  10394. the value of the parameter theEvent. The eventMask parameter specifies
  10395. which event types are of interest. GetOSEvent will return the next
  10396. available event of any type designated by the mask. If no event of any
  10397. of the designated types is available, GetOSEvent returns a null event
  10398. and a function result of FALSE; otherwise it returns TRUE.
  10399. \ OSEventAvail
  10400. 16
  10401. FUNCTION OSEventAvail (eventMask: INTEGER; VAR theEvent: EventRecord) :
  10402.                         BOOLEAN;
  10403.  
  10404.     __________________________________________________________________
  10405.  
  10406.     Trap macro  _OSEventAvail
  10407.  
  10408.     On entry    A0:  pointer to event record theEvent
  10409.                 D0:  eventMask (word)
  10410.  
  10411.     On exit     D0:  0 if not-null event returned, or
  10412.                     -1 if null event returned (byte)
  10413.     __________________________________________________________________
  10414.  
  10415.     OSEventAvail works exactly the same as GetOSEvent (above) except
  10416. that it doesn't remove the event from the event queue.
  10417.  
  10418. (note)
  10419.     An event returned by OSEventAvail will not be accessible
  10420.     later if in the meantime the queue becomes full and the
  10421.     event is discarded from it; since the events discarded
  10422.     are always the oldest ones in the queue, however, this
  10423.     will happen only in an unusually busy environment.
  10424. \ SetEventMask
  10425. 16
  10426. PROCEDURE SetEventMask (theMask: INTEGER);  [No trap macro]
  10427.  
  10428.     SetEventMask sets the system event mask to the specified event mask.
  10429. The Operating System Event Manager will post only those event types
  10430. that correspond to bits set in the mask. (As usual, it will not post
  10431. activate and update events, which are generated by the Window Manager
  10432. and not stored in the event queue.)  The system event mask is initially
  10433. set to post all except key-up events.
  10434.  
  10435. (warning)
  10436.     Because desk accessories may rely on receiving certain
  10437.     types of events, your application shouldn't set the
  10438.     system event mask to prevent any additional types
  10439.     (besides key-up) from being posted. You should use
  10440.     SetEventMask only to enable key-up events in the unusual
  10441.     case that your application needs to respond to them.
  10442. \ GetEvQHdr
  10443. 16
  10444. FUNCTION GetEvQHdr : QHdrPtr;  [No trap macro]
  10445.  
  10446.     GetEvQHdr retruns a pointer to the event queue.
  10447. \ PPostEvent
  10448. 16
  10449. FUNCTION PPostEvent (eventCode: INTEGER; eventMsg: LONGINT;
  10450.                         VAR qEl: EvQEl) : OSErr);
  10451.     ____________________________________________________________
  10452.  
  10453.         Trap macro  _PPostEvent
  10454.  
  10455.         On entry    A0:  eventCode (word)
  10456.                     D0:  eventMsg (long word)
  10457.  
  10458.         On exit     A0:  pointer to event queue entry
  10459.     ____________________________________________________________
  10460.     PPostEvent is identical to PostEvent except that it returns a
  10461. pointer to the created queue entry.
  10462. \ GetVInfo
  10463. 17
  10464. FUNCTION GetVInfo (drvNum: INTEGER; volName: StringPtr;
  10465.                   VAR vRefNum: INTEGER; VAR freeBytes: LONGINT)
  10466.                   : OSErr;  [Not in ROM]
  10467.  
  10468.     GetVInfo returns the name, reference number, and available space
  10469. (in bytes), in volName, vRefNum, and freeBytes, for the volume in
  10470. the drive specified by drvNum.
  10471.  
  10472. Result codes    noErr     No error
  10473.                 nsvErr    No default volume
  10474.                 paramErr  Bad drive number
  10475. \ GetVRefNum
  10476. 17
  10477. FUNCTION GetVRefNum (pathRefNum: INTEGER; VAR vRefNum: INTEGER)
  10478.                     : OSErr;  [Not in ROM]
  10479.  
  10480.     Given a path reference number in pathRefNum, GetVRefNum returns
  10481. the volume reference number in vRefNum.
  10482.  
  10483. Result codes    noErr       No error
  10484.                 rfNumErr    Bad reference number
  10485. \ GetVol
  10486. 17
  10487. FUNCTION GetVol (volName: StringPtr; VAR vRefNum: INTEGER)
  10488.                 : OSErr;  [Not in ROM]
  10489.  
  10490.     GetVol returns the name of the default volume in volName and its
  10491. volume reference number in vRefNum.
  10492.  
  10493. Result codes    noErr   No error
  10494.                 nsvErr  No such volume
  10495. \ SetVol
  10496. 17
  10497. FUNCTION SetVol (volName: StringPtr; vRefNum: INTEGER)
  10498.                 : OSErr;  [Not in ROM]
  10499.  
  10500.     SetVol sets the default volume to the mounted volume specified
  10501. by volName or vRefNum.
  10502.  
  10503. Result codes    noErr       No error
  10504.                 bdNamErr    Bad volume name
  10505.                 nsvErr      No such volume
  10506.                 paramErr    No default volume
  10507. \ FlushVol
  10508. 17
  10509. FUNCTION FlushVol (volName: StringPtr; vRefNum: INTEGER)
  10510.                     : OSErr;  [Not in ROM]
  10511.  
  10512.     On the volume specified by volName or vRefNum, FlushVol writes
  10513. the contents of the associated volume buffer and descriptive
  10514. information about the volume (if they’ve changed since the last
  10515. time FlushVol was called).
  10516.  
  10517. Result codes    noErr       No error
  10518.                 bdNamErr    Bad volume name
  10519.                 extFSErr    External file system
  10520.                 ioErr       I/O error
  10521.                 nsDrvErr    No such drive
  10522.                 nsvErr      No such volume
  10523.                 paramErr    No default volume
  10524. \ UnmountVol
  10525. 17
  10526. FUNCTION UnmountVol (volName: StringPtr; vRefNum: INTEGER)
  10527.                     : OSErr;  [Not in ROM]
  10528.  
  10529.     UnmountVol unmounts the volume specified by volName or vRefNum,
  10530. by calling FlushVol to flush the volume buffer, closing all
  10531. open files on the volume, and releasing the memory used for the volume.
  10532.  
  10533. Warning:  Don’t unmount the startup volume.
  10534.  
  10535. Result codes    noErr       No error
  10536.                 bdNamErr    Bad volume name
  10537.                 extFSErr    External file system
  10538.                 ioErr       I/O error
  10539.                 nsDrvErr    No such drive
  10540.                 nsvErr      No such volume
  10541.                 paramErr    No default volume
  10542. \ Eject
  10543. 17
  10544. FUNCTION Eject (volName: StringPtr; vRefNum: INTEGER)
  10545.                 : OSErr;  [Not in ROM]
  10546.  
  10547.     Eject flushes the volume specified by volName or vRefNum,
  10548. places it off-line, and then ejects the volume.
  10549.  
  10550. Result codes    noErr       No error
  10551.                 bdNamErr    Bad volume name
  10552.                 extFSErr    External file system
  10553.                 ioErr       I/O error
  10554.                 nsDrvErr    No such drive
  10555.                 nsvErr      No such volume
  10556.                 paramErr    No default volume
  10557. \ Create
  10558. 17
  10559. FUNCTION Create (fileName: Str255; vRefNum: INTEGER; creator: OSType;
  10560.                 fileType: OSType) : OSErr;  [Not in ROM]
  10561.  
  10562.     Create creates a new file (both forks) with the specified name,
  10563. file type, and creator on the specified volume. (File type and
  10564. creator are discussed in the Finder Interface chapter.)
  10565. The new file is unlocked and empty. The date and time of its
  10566. creation and last modification are set to the current date and time.
  10567.  
  10568. Result codes    noErr       No error
  10569.                 bdNamErr    Bad file name
  10570.                 dupFNErr    Duplicate file name and version
  10571.                 dirFulErr   File directory full
  10572.                 extFSErr    External file system
  10573.                 ioErr       I/O error
  10574.                 nsvErr      No such volume
  10575.                 vLckdErr    Software volume lock
  10576.                 wPrErr      Hardware volume lock
  10577. \ FSOpen
  10578. 17
  10579. FUNCTION FSOpen (fileName: Str255; vRefNum: INTEGER; VAR refNum: INTEGER)
  10580.                 : OSErr;  [Not in ROM]
  10581.  
  10582.     FSOpen creates an access path to the file having the name fileName
  10583. on the volume specified by vRefNum. A path reference number is returned
  10584. in refNum. The access path’s read/write permission is set to whatever
  10585. the file’s open permission allows.
  10586.  
  10587. Note:  There’s no guarantee that any bytes have been written until
  10588.        FlushVol is called.
  10589.  
  10590. Result codes    noErr       No error
  10591.                 bdNamErr    Bad file name
  10592.                 extFSErr    External file system
  10593.                 fnfErr      File not found
  10594.                 ioErr       I/O error
  10595.                 nsvErr      No such volume
  10596.                 opWrErr     File already open for writing
  10597.                 tmfoErr     Too many files open
  10598. \ FSRead
  10599. 17
  10600. FUNCTION FSRead (refNum: INTEGER; VAR count: LONGINT; buffPtr: Ptr)
  10601.                 : OSErr;  [Not in ROM]
  10602.  
  10603.     FSRead attempts to read the number of bytes specified by the count
  10604. parameter from the open file whose access path is specified by
  10605. refNum, and transfer them to the data buffer pointed to by buffPtr.
  10606. The read operation begins at the current mark, so you might want to
  10607. precede this with a call to SetFPos. If you try to read past the
  10608. logical end-of-file, FSRead moves the mark to the end-of-file and
  10609. returns eofErr as its function result. After the read is completed,
  10610. the number of bytes actually read is returned in the count parameter.
  10611.  
  10612. Result codes    noErr       No error
  10613.                 eofErr      End-of-file
  10614.                 extFSErr    External file system
  10615.                 fnOpnErr    File not open
  10616.                 ioErr       I/O error
  10617.                 paramErr    Negative count
  10618.                 rfNumErr    Bad reference number
  10619. \ FSWrite
  10620. 17
  10621. FUNCTION FSWrite (refNum: INTEGER; VAR count: LONGINT; buffPtr: Ptr)
  10622.                     : OSErr;  [Not in ROM]
  10623.  
  10624.     FSWrite takes the number of bytes specified by the count parameter
  10625. from the buffer pointed to by buffPtr and attempts to write them to
  10626. the open file whose access path is specified by refNum. The write
  10627. operation begins at the current mark, so you might want to precede
  10628. this with a call to SetFPos. After the write is completed, the number
  10629. of bytes actually written is returned in the count parameter.
  10630.  
  10631. Result codes    noErr       No error
  10632.                 dskFulErr   Disk full
  10633.                 fLckdErr    File locked
  10634.                 fnOpnErr    File not open
  10635.                 ioErr       I/O error
  10636.                 paramErr    Negative count
  10637.                 rfNumErr    Bad reference number
  10638.                 vLckdErr    Software volume lock
  10639.                 wPrErr      Hardware volume lock
  10640.                 wrPermErr   Read/write permission doesn’t allow writing
  10641. \ GetFPos
  10642. 17
  10643. FUNCTION GetFPos (refNum: INTEGER; VAR filePos: LONGINT)
  10644.                 : OSErr;  [Not in ROM]
  10645.  
  10646.     GetFPos returns, in filePos, the mark of the open file whose access
  10647. path is specified by refNum.
  10648.  
  10649. Result codes    noErr       No error
  10650.                 extFSErr    External file system
  10651.                 fnOpnErr    File not open
  10652.                 ioErr       I/O error
  10653.                 rfNumErr    Bad reference number
  10654. \ SetFPos
  10655. 17
  10656. FUNCTION SetFPos (refNum: INTEGER; posMode: INTEGER; posOff: LONGINT)
  10657.                     : OSErr;  [Not in ROM]
  10658.  
  10659.     SetFPos sets the mark of the open file whose access path is
  10660. specified by refNum to the position specified by posMode and posOff
  10661. (except when posMode is equal to fsAtMark, in which case posOff is
  10662. ignored). PosMode indicates how to position the mark; it must contain
  10663. one of the following values:
  10664.  
  10665. CONST fsAtMark    = 0;  {at current mark}
  10666.       fsFromStart = 1;  {set mark relative to beginning of file}
  10667.       fsFromLEOF  = 2;  {set mark relative to logical end-of-file}
  10668.       fsFromMark  = 3;  {set mark relative to current mark}
  10669.  
  10670.     If you specify fsAtMark, posOffset is ignored and the mark is left
  10671. wherever it’s currently positioned. If you choose to set the mark
  10672. (relative to either the beginning of the file, the logical end-of-file,
  10673. or the current mark), posOffset specifies the byte offset from the
  10674. chosen point (either positive or negative) where the mark should be set.
  10675. If you try to set the mark past the logical end-of-file, SetFPos moves
  10676. the mark to the end-of-file and returns eofErr as its function result.
  10677.  
  10678. Result codes    noErr       No error
  10679.                 eofErr      End-of-file
  10680.                 extFSErr    External file system
  10681.                 fnOpnErr    File not open
  10682.                 ioErr       I/O error
  10683.                 posErr      Attempt to position before start of file
  10684.                 rfNumErr    Bad reference number
  10685.  
  10686. \ GEtEOF
  10687. 17
  10688. FUNCTION GetEOF (refNum: INTEGER; VAR logEOF: LONGINT)
  10689.                 : OSErr;  [Not in ROM]
  10690.  
  10691.     GetEOF returns, in logEOF, the logical end-of-file of the open
  10692. file whose access path is specified by refNum.
  10693.  
  10694. Result codes    noErr       No error
  10695.                 extFSErr    External file system
  10696.                 fnOpnErr    File not open
  10697.                 ioErr       I/O error
  10698.                 rfNumErr    Bad reference number
  10699. \ SetEOF
  10700. 17
  10701. FUNCTION SetEOF (refNum: INTEGER; logEOF: LONGINT)
  10702.                 : OSErr;  [Not in ROM]
  10703.  
  10704.     SetEOF sets the logical end-of-file of the open file whose access
  10705. path is specified by refNum to the position specified by logEOF.
  10706. If you attempt to set the logical end-of-file beyond the physical
  10707. end-of-file, the physical end-of-file is set to one byte beyond
  10708. the end of the next free allocation block; if there isn’t enough
  10709. space on the volume, no change is made, and SetEOF returns dskFulErr
  10710. as its function result. If logEOF is 0, all space occupied by the file
  10711. on the volume is released.
  10712.  
  10713. Result codes    noErr       No error
  10714.                 dskFulErr   Disk full
  10715.                 extFSErr    External file system
  10716.                 fLckdErr    File locked
  10717.                 fnOpnErr    File not open
  10718.                 ioErr       I/O error
  10719.                 rfNumErr    Bad reference number
  10720.                 vLckdErr    Software volume lock
  10721.                 wPrErr      Hardware volume lock
  10722.                 wrPermErr   Read/write permission doesn’t allow writing
  10723. \ Allocate
  10724. 17
  10725. FUNCTION Allocate (refNum: INTEGER; VAR count: LONGINT)
  10726.                     : OSErr;  [Not in ROM]
  10727.  
  10728.     Allocate adds the number of bytes specified by the count parameter
  10729. to the open file whose access path is specified by refNum, and sets the
  10730. physical end-of-file to one byte beyond the last block allocated.
  10731. The number of bytes actually allocated is rounded up to the nearest
  10732. multiple of the allocation block size, and returned in the count
  10733. parameter. If there isn’t enough empty space on the volume to satisfy
  10734. the allocation request, Allocate allocates the rest of the space on the
  10735. volume and returns dskFulErr as its function result.
  10736.  
  10737. Result codes    noErr       No error
  10738.                 dskFulErr   Disk full
  10739.                 fLckdErr    File locked
  10740.                 fnOpnErr    File not open
  10741.                 ioErr       I/O error
  10742.                 rfNumErr    Bad reference number
  10743.                 vLckdErr    Software volume lock
  10744.                 wPrErr      Hardware volume lock
  10745.                 wrPermErr   Read/write permission doesn’t allow writing
  10746. \ FSClose
  10747. 17
  10748. FUNCTION FSClose (refNum: INTEGER) : OSErr;  [Not in ROM]
  10749.  
  10750.     FSClose removes the access path specified by refNum, writes the
  10751. contents of the volume buffer to the volume, and updates the file’s
  10752. entry in the file directory.
  10753.  
  10754. Note:  There’s no guarantee that any bytes have been written until
  10755.        FlushVol is called.
  10756.  
  10757. Result codes    noErr       No error
  10758.                 extFSErr    External file system
  10759.                 fnfErr      File not found
  10760.                 fnOpnErr    File not open
  10761.                 ioErr       I/O error
  10762.                 nsvErr      No such volume
  10763.                 rfNumErr    Bad reference number
  10764. \ GetFInfo
  10765. 17
  10766. FUNCTION GetFInfo (fileName: Str255; vRefNum: INTEGER; VAR
  10767.                     fndrInfo: FInfo) : OSErr;  [Not in ROM]
  10768.  
  10769.     For the file having the name fileName on the specified volume,
  10770. GetFInfo returns information used by the Finder in fndrInfo
  10771. (see the section “File Information Used by the Finder”).
  10772.  
  10773. Result codes    noErr       No error
  10774.                 bdNamErr    Bad file name
  10775.                 extFSErr    External file system
  10776.                 fnfErr      File not found
  10777.                 ioErr       I/O error
  10778.                 nsvErr      No such volume
  10779.                 paramErr    No default volume
  10780. \ SetFInfo
  10781. 17
  10782. FUNCTION SetFInfo (fileName: Str255; vRefNum: INTEGER;
  10783.                     fndrInfo: FInfo) : OSErr;  [Not in ROM]
  10784.  
  10785.     For the file having the name fileName on the specified volume,
  10786. SetFInfo sets information used by the Finder to fndrInfo (see
  10787. the section “File Information Used by the Finder”).
  10788.  
  10789. Result codes    noErr       No error
  10790.                 extFSErr    External file system
  10791.                 fLckdErr    File locked
  10792.                 fnfErr      File not found
  10793.                 ioErr       I/O error
  10794.                 nsvErr      No such volume
  10795.                 vLckdErr    Software volume lock
  10796.                 wPrErr      Hardware volume lock
  10797. \ SetFLock
  10798. 17
  10799. FUNCTION SetFLock (fileName: Str255; vRefNum: INTEGER)
  10800.                 : OSErr;  [Not in ROM]
  10801.  
  10802.     SetFLock locks the file having the name fileName on the specified
  10803. volume. Access paths currently in use aren’t affected.
  10804.  
  10805. Result codes    noErr       No error
  10806.                 extFSErr    External file system
  10807.                 fnfErr      File not found
  10808.                 ioErr       I/O error
  10809.                 nsvErr      No such volume
  10810.                 vLckdErr    Software volume lock
  10811.                 wPrErr      Hardware volume lock
  10812. \ RstFLock
  10813. 17
  10814. FUNCTION RstFLock (fileName: Str255; vRefNum: INTEGER)
  10815.                     : OSErr;  [Not in ROM]
  10816.  
  10817.     RstFLock unlocks the file having the name fileName on the specified
  10818. volume. Access paths currently in use aren’t affected.
  10819.  
  10820. Result codes    noErr       No error
  10821.                 extFSErr    External file system
  10822.                 fnfErr      File not found
  10823.                 ioErr       I/O error
  10824.                 nsvErr      No such volume
  10825.                 vLckdErr    Software volume lock
  10826.                 wPrErr      Hardware volume lock
  10827. \ Rename
  10828. 17
  10829. FUNCTION Rename (oldName: Str255; vRefNum: INTEGER; newName: Str255)
  10830.                 : OSErr;  [Not in ROM]
  10831.  
  10832.     Given a file name in oldName, Rename changes the name of the file to
  10833. newName. Access paths currently in use aren’t affected. Given a volume
  10834. name in oldName or a volume reference number in vRefNum, Rename changes
  10835. the name of the specified volume to newName.
  10836.  
  10837. Warning:  If you’re renaming a volume, be sure that both names end with
  10838.           a colon.
  10839.  
  10840. Result codes    noErr       No error
  10841.                 bdNamErr    Bad file name
  10842.                 dirFulErr   Directory full
  10843.                 dupFNErr    Duplicate file name
  10844.                 extFSErr    External file system
  10845.                 fLckdErr    File locked
  10846.                 fnfErr      File not found
  10847.                 fsRnErr     Problem during rename
  10848.                 ioErr       I/O error
  10849.                 nsvErr      No such volume
  10850.                 paramErr    No default volume
  10851.                 vLckdErr    Software volume lock
  10852.                 wPrErr      Hardware volume lock
  10853. \ FSDelete
  10854. 17
  10855. FUNCTION FSDelete (fileName: Str255; vRefNum: INTEGER)
  10856.                     : OSErr;  [Not in ROM]
  10857.  
  10858.     FSDelete removes the closed file having the name fileName from the
  10859. specified volume.
  10860.  
  10861. Note:  This function will delete both forks of a file.
  10862.  
  10863. Result codes    noErr       No error
  10864.                 bdNamErr    Bad file name
  10865.                 extFSErr    External file system
  10866.                 fBsyErr     File busy
  10867.                 fLckdErr    File locked
  10868.                 fnfErr      File not found
  10869.                 ioErr       I/O error
  10870.                 nsvErr      No such volume
  10871.                 vLckdErr    Software volume lock
  10872.                 wPrErr      Hardware volume lock
  10873. \ OpenRF
  10874. 17
  10875. FUNCTION OpenRF (fileName: Str255; vRefNum: INTEGER;
  10876.                 VAR refNum: INTEGER) : OSErr;  [Not in ROM]
  10877.  
  10878.     OpenRF is similar to FSOpen; the only difference is that OpenRF
  10879. opens the resource fork of the specified file rather than the data fork.
  10880. A path reference number is returned in refNum. The access path’s
  10881. read/write permission is set to whatever the file’s open permission
  10882. allows.
  10883.  
  10884. Note:  Normally you should access a file’s resource fork through the
  10885.        routines of the Resource Manager rather than the File Manager.
  10886.        OpenRF doesn’t read the resource map into memory; it’s really
  10887.        only useful for block-level operations such as copying files.
  10888.  
  10889. Result codes    noErr       No error
  10890.                 bdNamErr    Bad file name
  10891.                 extFSErr    External file system
  10892.                 fnfErr      File not found
  10893.                 ioErr       I/O error
  10894.                 nsvErr      No such volume
  10895.                 opWrErr     File already open for writing
  10896.                 tmfoErr     Too many files open
  10897. \ FInitQueue
  10898. 17
  10899. PROCEDURE InitQueue;
  10900.  
  10901. Trap macro  _InitQueue
  10902.  
  10903. FInitQueue clears all queued File Manager calls except the current one.
  10904. \ PBMountVol
  10905. 17
  10906. FUNCTION PBMountVol (paramBlock: ParmBlkPtr) : OSErr;
  10907.  
  10908. Trap macro  _MountVol
  10909.  
  10910. Parameter block
  10911.     <—  16  ioResult    word
  10912.     <–> 22  ioVRefNum   word
  10913.  
  10914.     PBMountVol mounts the volume in the drive specified by ioVRefNum,
  10915. and returns a volume reference number in ioVRefNum. If there are no
  10916. volumes already mounted, this volume becomes the default volume.
  10917. PBMountVol is always executed synchronously.
  10918.  
  10919. Note:  When mounting hierarchical volumes, PBMountVol opens two files
  10920.        needed for maintaining file directory and file mapping
  10921.        information. PBMountVol can fail if there are no access paths
  10922.        available for these two files; it will return tmfoErr as its
  10923.        function result.
  10924.  
  10925. Result codes    noErr       No error
  10926.                 badMDBErr   Bad master directory block
  10927.                 extFSErr    External file system
  10928.                 ioErr       I/O error
  10929.                 memFullErr  Not enough room in heap zone
  10930.                 noMacDskErr Not a Macintosh disk
  10931.                 nsDrvErr    No such drive
  10932.                 paramErr    Bad drive number
  10933.                 tmfoErr     Too many files open
  10934.                 volOnLinErr Volume already on-line
  10935. \ PBGetVInfo
  10936. 17
  10937. FUNCTION PBGetVInfo (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr;
  10938.  
  10939. Trap macro  _GetVolInfo
  10940.  
  10941. Parameter block
  10942.     —>  12      ioCompletion    pointer
  10943.     <—  16      ioResult        word
  10944.     <–> 18      ioNamePtr       pointer
  10945.     <–> 22      ioVRefNum       word
  10946.     —>  28      ioVolIndex      word
  10947.     <—  30      ioVCrDate       long word
  10948.     <—  34      ioVLsBkUp       long word
  10949.     <—  38      ioVAtrb         word
  10950.     <—  40      ioVNmFls        word
  10951.     <—  42      ioVDirSt        word
  10952.     <—  44      ioVBlLn         word
  10953.     <—  46      ioVNmAlBlks     word
  10954.     <—  48      ioVAlBlkSiz     long word
  10955.     <—  52      ioVClpSiz       long word
  10956.     <—  56      ioAlBlSt        word
  10957.     <—  58      ioVNxtFNum      long word
  10958.     <—  62      ioVFrBlk        word
  10959.  
  10960.     PBGetVInfo returns information about the specified volume. If
  10961. ioVolIndex is positive, the File Manager attempts to use it to find the
  10962. volume; for instance, if ioVolIndex is 2, the File Manager will attempt
  10963. to access the second mounted volume. If ioVolIndex is negative, the
  10964. File Manager uses ioNamePtr and ioVRefNum in the standard way (described
  10965. in the section “Specifying Volumes, Directories, and Files”) to
  10966. determine which volume. If ioVolIndex is 0, the File Manager attempts
  10967. to access the volume by using ioVRefNum only. The volume reference
  10968. number is returned in ioVRefNum, and a pointer to the volume name is
  10969. returned in ioNamePtr (unless ioNamePtr is NIL).
  10970.  
  10971.     If a working directory reference number is passed in ioVRefNum (or
  10972. if the default directory is a subdirectory), the number of files and
  10973. directories in the specified directory (the directory’s valence) will be
  10974. returned in ioVNmFls. Also, the volume reference number won’t be
  10975. returned; ioVRefNum will still contain the working directory reference
  10976. number.
  10977.  
  10978. Warning:  IOVNmAlBlks and ioVFrBlks, which are actually unsigned
  10979.           integers, are clipped to 31744 ($7C00) regardless of the size
  10980.           of the volume.
  10981.  
  10982. Result codes    noErr       No error
  10983.                 nsvErr      No such volume
  10984.                 paramErr    No default volume
  10985. \ PBHGetVInfo
  10986. 17
  10987. FUNCTION PBHGetVInfo (paramBlock: HParmBlkPtr; async: BOOLEAN) : OSErr;
  10988.  
  10989. Trap macro  _HGetVInfo
  10990.  
  10991. Parameter block
  10992.     —>  12  ioCompletion    pointer
  10993.     <—  16  ioResult        word
  10994.     <–> 18  ioNamePtr       pointer
  10995.     <–> 22  ioVRefNum       word
  10996.     —>  28  ioVolIndex      word
  10997.     <—  30  ioVCrDate       long word
  10998.     <—  34  ioVLsMod        long word
  10999.     <—  38  ioVAtrb         word
  11000.     <—  40  ioVNmFls        word
  11001.     <—  42  ioVBitMap       word
  11002.     <—  44  ioVAllocPtr     word
  11003.     <—  46  ioVNmAlBlks     word
  11004.     <—  48  ioVAlBlkSiz     long word
  11005.     <—  52  ioVClpSiz       long word
  11006.     <—  56  ioAlBlSt        word
  11007.     <—  58  ioVNxtFNum      long word
  11008.     <—  62  ioVFrBlk        word
  11009.     <—  64  ioVSigWord      word
  11010.     <—  66  ioVDrvInfo      word
  11011.     <—  68  ioVDRefNum      word
  11012.     <—  70  ioVFSID         word
  11013.     <—  72  ioVBkUp         long word
  11014.     <—  76  ioVSeqNum       word
  11015.     <—  78  ioVWrCnt        long word
  11016.     <—  82  ioVFilCnt       long word
  11017.     <—  86  ioVDirCnt       long word
  11018.     <—  90  ioVFndrInfo     32 bytes
  11019.  
  11020.     PBHGetVInfo is similar in function to PBGetVInfo but returns a
  11021. larger parameter block. In addition, PBHGetVInfo always returns the
  11022. volume reference number in ioVRefNum (regardless of what was passed in).
  11023. Also, ioVNmAlBlks and ioVFrBlks are not clipped as they are by
  11024. PBGetVInfo.
  11025.  
  11026. Result codes    noErr       No error
  11027.                 nsvErr      No such volume
  11028.                 paramErr    No default volume
  11029. \ PBSetVInfo
  11030. 17
  11031. FUNCTION PBSetVInfo (paramBlock: HParmBlkPtr; async: BOOLEAN) : OSErr;
  11032.  
  11033. Trap macro  _SetVolInfo
  11034.  
  11035. Parameter block
  11036.     —>  12  ioCompletion    pointer
  11037.     <—  16  ioResult        word
  11038.     —>  18  ioNamePtr       pointer
  11039.     —>  22  ioVRefNum       word
  11040.     —>  30  ioVCrDate       long word
  11041.     —>  34  ioVLsMod        long word
  11042.     —>  38  ioVAtrb         word
  11043.     —>  52  ioVClpSiz       long word
  11044.     —>  72  ioVBkUp         long word
  11045.     —>  76  ioVSeqNum       word
  11046.     —>  90  ioVFndrInfo     32 bytes
  11047.  
  11048.     PBSetVInfo lets you modify information about volumes. A pointer to
  11049. a new name for the volume can be specified in ioNamePtr. The date and
  11050. time of the volume’s creation and modification can be set with ioVCrDate
  11051. and ioVLsMod respectively. Only bit 15 of ioVAtrb can be changed;
  11052. setting it locks the volume.
  11053.  
  11054. Note: The volume cannot be specified by name; you must use either the
  11055.        volume reference number or the drive number.
  11056.  
  11057. Warning:  PBSetVInfo operates only with the hierarchical version of the
  11058.           File Manager; if used on a Macintosh equipped only with the
  11059.           64K ROM version of the File Manager, it will generate a system
  11060.           error.
  11061.  
  11062. Result codes    noErr       No error
  11063.                 nsvErr      No such volume
  11064.                 paramErr    No default volume
  11065. \ PBGetVol
  11066. 17
  11067. FUNCTION PBGetVol (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr;
  11068.  
  11069. Trap macro  _GetVol
  11070.  
  11071. Parameter block
  11072.     —>  12  ioCompletion    pointer
  11073.     <—  16  ioResult        word
  11074.     <—  18  ioNamePtr       pointer
  11075.     <—  22  ioVRefNum       word
  11076.  
  11077.     PBGetVol returns a pointer to the name of the default volume in
  11078. ioNamePtr (unless ioNamePtr is NIL) and its volume reference number in
  11079. ioVRefNum. If a default directory was set with a previous PBSetVol
  11080. call, a pointer to its name will be returned in ioNamePtr and its
  11081. working directory reference number in ioVRefNum.
  11082.  
  11083. Result codes    noErr   No error
  11084.                 nsvErr  No default volume
  11085. \ PBHGetVol
  11086. 17
  11087. FUNCTION PBHGetVol (paramBlock: WDPBPtr; async: BOOLEAN) : OSErr;
  11088.  
  11089. Trap macro  _HGetVol
  11090.  
  11091. Parameter block
  11092.     —>  12  ioCompletion    pointer
  11093.     <—  16  ioResult        word
  11094.     <—  18  ioNamePtr       pointer
  11095.     <—  22  ioVRefNum       word
  11096.     <—  28  ioWDProcID      long word
  11097.     <—  32  ioWDVRefNum     word
  11098.     <—  48  ioWDDirID       long word
  11099.  
  11100.     PBHGetVol returns the default volume and directory last set by
  11101. either a PBSetVol or a PBHSetVol call. The reference number of the
  11102. default volume is returned in ioVRefNum.
  11103.  
  11104. Warning:  IOVRefNum will return a working directory reference number
  11105.           (instead of the volume reference number) if, in the last call
  11106.           to PBSetVol or PBHSetVol, a working directory reference number
  11107.           was passed in this field.
  11108.  
  11109.     The volume reference number of the volume on which the default
  11110. directory exists is returned in ioWDVRefNum. The directory ID of the
  11111. default directory is returned in ioWDDirID.
  11112.  
  11113. Result codes    noErr   No error
  11114.                 nsvErr  No default volume
  11115. \ PBSetVol
  11116. 17
  11117. FUNCTION PBSetVol (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr;
  11118.  
  11119. Trap macro  _SetVol
  11120.  
  11121. Parameter block
  11122.     —>  12  ioCompletion    pointer
  11123.     <—  16  ioResult        word
  11124.     —>  18  ioNamePtr       pointer
  11125.     —>  22  ioVRefNum       word
  11126.  
  11127.     PBSetVol sets the default volume to the mounted volume specified by
  11128. ioNamePtr or ioVRefNum. On hierarchical volumes, PBSetVol also sets the
  11129. root directory as the default directory.
  11130.  
  11131. Result codes    noErr       No error
  11132.                 bdNamErr    Bad volume name
  11133.                 nsvErr      No such volume
  11134.                 paramErr    No default volume
  11135. \ PBHSetVol
  11136. 17
  11137. FUNCTION PBHSetVol (paramBlock: WDPBPtr; async: BOOLEAN) : OSErr;
  11138.  
  11139. Trap macro  _HSetVol
  11140.  
  11141. Parameter block
  11142.     —>  12  ioCompletion    pointer
  11143.     <—  16  ioResult        word
  11144.     —>  18  ioNamePtr       pointer
  11145.     —>  22  ioVRefNum       word
  11146.     —>  48  ioWDDirID       long word
  11147.  
  11148.     PBHSetVol sets both the default volume and the default directory.
  11149. The default directory to be used can be specified by either a volume
  11150. reference number or a working directory reference number in ioVRefNum, a
  11151. directory ID in ioWDDirID, or a pointer to a pathname (possibly NIL) in
  11152. ioNamePtr.
  11153.  
  11154. Note:  Both the default volume and  the default directory are used in
  11155.        calls made with no volume name and a volume reference number of
  11156.        zero.
  11157.  
  11158. Result codes    noErr   No error
  11159.                 nsvErr  No default volume
  11160. \ PBFlushVol
  11161. 17
  11162. FUNCTION PBFlushVol (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr;
  11163.  
  11164. Trap macro  _FlushVol
  11165.  
  11166. Parameter block
  11167.     —>  12  ioCompletion    pointer
  11168.     <—  16  ioResult        word
  11169.     —>  18  ioNamePtr       pointer
  11170.     —>  22  ioVRefNum       word
  11171.  
  11172.     On the volume specified by ioNamePtr or ioVRefNum, PBFlushVol writes
  11173. descriptive information about the volume, the contents of the associated
  11174. volume buffer, and all access path buffers for the volume (if they’ve
  11175. changed since the last time PBFlushVol was called).
  11176.  
  11177. Note:  The date and time of the last modification to the volume are set
  11178.        when the modification is made, not when the volume is flushed.
  11179.  
  11180. Result codes    noErr       No error
  11181.                 bdNamErr    Bad volume name
  11182.                 extFSErr    External file system
  11183.                 ioErr       I/O error
  11184.                 nsDrvErr    No such drive
  11185.                 nsvErr      No such volume
  11186.                 paramErr    No default volume
  11187. \ PBUnmountVol
  11188. 17
  11189. FUNCTION PBUnmountVol (paramBlock: ParmBlkPtr) : OSErr;
  11190.  
  11191. Trap macro  _UnmountVol
  11192.  
  11193. Parameter block
  11194.     <—  16  ioResult    word
  11195.     —>  18  ioNamePtr   pointer
  11196.     —>  22  ioVRefNum   word
  11197.  
  11198.     PBUnmountVol unmounts the volume specified by ioNamePtr or
  11199. ioVRefNum, by calling PBFlushVol to flush the volume, closing all open
  11200. files on the volume, and releasing the memory used for the volume.
  11201. PBUnmountVol is always executed synchronously.
  11202.  
  11203. Warning:  Don’t unmount the startup volume.
  11204.  
  11205. Note:  Unmounting a volume does not close working directories; to
  11206.        release the memory allocated to a working directory, call
  11207.        PBCloseWD.
  11208.  
  11209. Result codes    noErr       No error
  11210.                 bdNamErr    Bad volume name
  11211.                 extFSErr    External file system
  11212.                 ioErr       I/O error
  11213.                 nsDrvErr    No such drive
  11214.                 nsvErr      No such volume
  11215.                 paramErr    No default volume
  11216. \ PBOffLine
  11217. 17
  11218. FUNCTION PBOffLine (paramBlock: ParmBlkPtr) : OSErr;
  11219.  
  11220. Trap macro  _OffLine
  11221.  
  11222. Parameter block
  11223.     —>  12  ioCompletion    pointer
  11224.     <—  16  ioResult    word
  11225.     —>  18  ioNamePtr   pointer
  11226.     —>  22  ioVRefNum   word
  11227.  
  11228.     PBOffLine places off-line the volume specified by ioNamePtr or
  11229. ioVRefNum, by calling PBFlushVol to flush the volume and releasing all
  11230. the memory used for the volume except for the volume control block.
  11231. PBOffLine is always executed synchronously.
  11232.  
  11233. Result codes    noErr       No error
  11234.                 bdNamErr    Bad volume name
  11235.                 extFSErr    External file system
  11236.                 ioErr       I/O error
  11237.                 nsDrvErr    No such drive
  11238.                 nsvErr      No such volume
  11239.                 paramErr    No default volume
  11240. \ PBEject
  11241. 17
  11242. FUNCTION PBEject (paramBlock: ParmBlkPtr) : OSErr;
  11243.  
  11244. Trap macro  _Eject
  11245.  
  11246. Parameter block
  11247.     —>  12  ioCompletion    pointer
  11248.     <—  16  ioResult        word
  11249.     —>  18  ioNamePtr       pointer
  11250.     —>  22  ioVRefNum       word
  11251.  
  11252.     PBEject flushes the volume specified by ioNamePtr or ioVRefNum,
  11253. places it off-line, and then ejects the volume.
  11254. ________________________________________________________________________
  11255.  
  11256. Assembly-language note:  You may invoke the macro _Eject asynchronously;
  11257. the first part of the call is executed synchronously, and the actual
  11258. ejection is executed asynchronously.
  11259. ________________________________________________________________________
  11260. Result codes    noErr       No error
  11261.                 bdNamErr    Bad volume name
  11262.                 extFSErr    External file system
  11263.                 ioErr       I/O error
  11264.                 nsDrvErr    No such drive
  11265.                 nsvErr      No such volume
  11266.                 paramErr    No default volume
  11267. \ PBOpen
  11268. 17
  11269. FUNCTION PBOpen (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr;
  11270.  
  11271. Trap macro  _Open
  11272.  
  11273. Parameter block
  11274.     —>  12  ioCompletion    pointer
  11275.     <—  16  ioResult        word
  11276.     —>  18  ioNamePtr       pointer
  11277.     —>  22  ioVRefNum       word
  11278.     <—  24  ioRefNum        word
  11279.     —>  26  ioVersNum       byte
  11280.     —>  27  ioPermssn       byte
  11281.     —>  28  ioMisc          pointer
  11282.  
  11283.     PBOpen creates an access path to the file having the name pointed to
  11284. by ioNamePtr (and on flat volumes, the version number ioVersNum) on the
  11285. volume specified by ioVRefNum. A path reference number is returned in
  11286. ioRefNum.
  11287.  
  11288.     IOMisc either points to a portion of memory (522 bytes) to be used
  11289. as the access path’s buffer, or is NIL if you want the volume buffer to
  11290. be used instead.
  11291.  
  11292. Warning:  All access paths to a single file that’s opened multiple times
  11293.           should share the same buffer so that they will read and write
  11294.           the same data.
  11295.  
  11296.     IOPermssn specifies the path’s read/write permission. A path can be
  11297. opened for writing even if it accesses a file on a locked volume, and an
  11298. error won’t be returned until a PBWrite, PBSetEOF, or PBAllocate call is
  11299. made.
  11300.  
  11301.     If you attempt to open a locked file for writing, PBOpen will return
  11302. permErr as its function result. If you request exclusive read/write
  11303. permission but another access path already has write permission (whether
  11304. write only, exclusive read/write, or shared read/write), PBOpen will
  11305. return the reference number of the existing access path in ioRefNum and
  11306. opWrErr as its function result. Similarly, if you request shared
  11307. read/write permission but another access path already has exclusive
  11308. read/write permission, PBOpen will return the reference number of the
  11309. access path in ioRefNum and opWrErr as its function result.
  11310.  
  11311. Result codes    noErr       No error
  11312.                 bdNamErr    Bad file name
  11313.                 extFSErr    External file system
  11314.                 fnfErr      File not found
  11315.                 ioErr       I/O error
  11316.                 nsvErr      No such volume
  11317.                 opWrErr     File already open for writing
  11318.                 permErr     Attempt to open locked file for writing
  11319.                 tmfoErr     Too many files open
  11320. \ PBHOpen
  11321. 17
  11322. FUNCTION PBHOpen (paramBlock: HParmBlkPtr; async: BOOLEAN) : OSErr;
  11323.  
  11324. Trap macro  _HOpen
  11325.  
  11326. Parameter block
  11327.     —>  12  ioCompletion    pointer
  11328.     <—  16  ioResult        word
  11329.     —>  18  ioNamePtr       pointer
  11330.     —>  22  ioVRefNum       word
  11331.     <—  24  ioRefNum        word
  11332.     —>  27  ioPermssn       byte
  11333.     —>  28  ioMisc          pointer
  11334.     —>  48  ioDirID         long word
  11335.  
  11336.     PBHOpen is identical to PBOpen except that it accepts a directory ID
  11337. in ioDirID.
  11338.  
  11339. Result codes    noErr       No error
  11340.                 bdNamErr    Bad file name
  11341.                 dirNFErr    Directory not found or incomplete pathname
  11342.                 extFSErr    External file system
  11343.                 fnfErr      File not found
  11344.                 ioErr       I/O error
  11345.                 nsvErr      No such volume
  11346.                 opWrErr     File already open for writing
  11347.                 permErr     Attempt to open locked file for writing
  11348.                 tmfoErr     Too many files open
  11349.  
  11350. \ PBOpenRF
  11351. 17
  11352. FUNCTION PBOpenRF (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr;
  11353.  
  11354. Trap macro  _OpenRF
  11355.  
  11356. Parameter block
  11357.     —>  12  ioCompletion    pointer
  11358.     <—  16  ioResult        word
  11359.     —>  18  ioNamePtr       pointer
  11360.     —>  22  ioVRefNum       word
  11361.     <—  24  ioRefNum        word
  11362.     —>  26  ioVersNum       byte
  11363.     —>  27  ioPermssn       byte
  11364.     —>  28  ioMisc          pointer
  11365.  
  11366.     PBOpenRF is identical to PBOpen, except that it opens the file’s
  11367. resource fork instead of its data fork.
  11368.  
  11369. Note:  Normally you should access a file’s resource fork through the
  11370.        routines of the Resource Manager rather than the File Manager.
  11371.        PBOpenRF doesn’t read the resource map into memory; it’s really
  11372.        only useful for block-level operations such as copying files.
  11373.  
  11374. Result codes    noErr       No error
  11375.                 bdNamErr    Bad file name
  11376.                 extFSErr    External file system
  11377.                 fnfErr      File not found
  11378.                 ioErr       I/O error
  11379.                 nsvErr      No such volume
  11380.                 opWrErr     File already open for writing
  11381.                 permErr     Attempt to open locked file for writing
  11382.                 tmfoErr     Too many files open
  11383. \ PBHOpenRF
  11384. 17
  11385. FUNCTION PBHOpenRF (paramBlock: HParmBlkPtr; async: BOOLEAN) : OSErr;
  11386.  
  11387. Trap macro  _HOpenRF
  11388.  
  11389. Parameter block
  11390.     —>  12  ioCompletion    pointer
  11391.     <—  16  ioResult        word
  11392.     —>  18  ioNamePtr       pointer
  11393.     —>  22  ioVRefNum       word
  11394.     <—  24  ioRefNum        word
  11395.     —>  27  ioPermssn       byte
  11396.     —>  28  ioMisc          pointer
  11397.     —>  48  ioDirID         long word
  11398.  
  11399.     PBHOpenRF is identical to PBOpenRF except that it accepts a
  11400. directory ID in ioDirID.
  11401.  
  11402. Result codes    noErr       No error
  11403.                 bdNamErr    Bad file name
  11404.                 dirNFErr    Directory not found or incomplete pathname
  11405.                 extFSErr    External file system
  11406.                 fnfErr      File not found
  11407.                 ioErr       I/O error
  11408.                 nsvErr      No such volume
  11409.                 opWrErr     File already open for writing
  11410.                 permErr     Attempt to open locked file for writing
  11411.                 tmfoErr     Too many files open
  11412. \ PBLockRange
  11413. 17
  11414. FUNCTION PBLockRange (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr;
  11415.  
  11416. Trap macro  _LockRng
  11417.  
  11418. Parameter block
  11419.     —>  12  ioCompletion    pointer
  11420.     <—  16  ioResult        word
  11421.     —>  24  ioRefNum        word
  11422.     —>  36  ioReqCount      long word
  11423.     —>  44  ioPosMode       word
  11424.     —>  46  ioPosOffset     long word
  11425.  
  11426.     On a file opened with a shared read/write permission, PBLockRange is
  11427. used in conjunction with PBRead and PBWrite to lock a certain portion of
  11428. the file. PBLockRange uses the same parameters as both PBRead and
  11429. PBWrite; by calling it immediately before PBRead, you can use the
  11430. information present in the parameter block for the PBRead call.
  11431.  
  11432.     When you’re finished with the data (typically after a call to
  11433. PBWrite), be sure to call PBUnlockRange to free up that portion of the
  11434. file for subsequent PBRead calls.
  11435.  
  11436. Warning:  PBLockRange operates only with the hierarchical version of the
  11437.           File Manager; if used on a Macintosh equipped only with the
  11438.           64K ROM version of the File Manager, it will generate a system
  11439.           error.
  11440.  
  11441. Result codes    noErr       No error
  11442.                 eofErr      End-of-file
  11443.                 extFSErr    External file system
  11444.                 fnOpnErr    File not open
  11445.                 ioErr       I/O error
  11446.                 paramErr    Negative ioReqCount
  11447.                 rfNumErr    Bad reference number
  11448. \ PBUnlockRange
  11449. 17
  11450. FUNCTION PBUnlockRange (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr;
  11451.  
  11452. Trap macro  _UnlockRng
  11453.  
  11454. Parameter block
  11455.     —>  12  ioCompletion    pointer
  11456.     <—  16  ioResult        word
  11457.     —>  24  ioRefNum        word
  11458.     —>  36  ioReqCount      long word
  11459.     —>  44  ioPosMode       word
  11460.     —>  46  ioPosOffset     long word
  11461.  
  11462.     PBUnlockRange is used in conjunction with PBRead and PBWrite to
  11463. unlock a certain portion of a file that you locked with PBLockRange.
  11464. PBUnlockRange uses the same parameters as both PBRead and PBWrite; by
  11465. calling it immediately after PBWrite, you can use the information
  11466. present in the parameter block to unlock the portion of the file that
  11467. was just written.
  11468.  
  11469. Warning:  PBUnlockRange operates only with the hierarchical version of
  11470.           the File Manager; if used on a Macintosh equipped only with
  11471.           the 64K ROM version of the File Manager, it will generate a
  11472.           system error.
  11473.  
  11474. Result codes    noErr       No error
  11475.                 eofErr      End-of-file
  11476.                 extFSErr    External file system
  11477.                 fnOpnErr    File not open
  11478.                 ioErr       I/O error
  11479.                 paramErr    Negative ioReqCount
  11480.                 rfNumErr    Bad reference number
  11481. \ PBRead
  11482. 17
  11483. FUNCTION PBRead (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr;
  11484.  
  11485. Trap macro  _Read
  11486.  
  11487. Parameter block
  11488.     —>  12  ioCompletion    pointer
  11489.     <—  16  ioResult        word
  11490.     —>  24  ioRefNum        word
  11491.     —>  32  ioBuffer        pointer
  11492.     —>  36  ioReqCount      long word
  11493.     <—  40  ioActCount      long word
  11494.     —>  44  ioPosMode       word
  11495.     <–> 46  ioPosOffset     long word
  11496.  
  11497.     PBRead attempts to read ioReqCount bytes from the open file whose
  11498. access path is specified by ioRefNum, and transfer them to the data
  11499. buffer pointed to by ioBuffer. The position of the mark is specified by
  11500. ioPosMode and ioPosOffset. If you try to read past the logical
  11501. end-of-file, PBRead moves the mark to the end-of-file and returns eofErr
  11502. as its function result. After the read is completed, the mark is
  11503. returned in ioPosOffset and the number of bytes actually read is
  11504. returned in ioActCount.
  11505.  
  11506. Result codes    noErr       No error
  11507.                 eofErr      End-of-file
  11508.                 extFSErr    External file system
  11509.                 fnOpnErr    File not open
  11510.                 ioErr       I/O error
  11511.                 paramErr    Negative ioReqCount
  11512.                 rfNumErr    Bad reference number
  11513. \ PBWrite
  11514. 17
  11515. FUNCTION PBWrite (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr;
  11516.  
  11517. Trap macro  _Write
  11518.  
  11519. Parameter block
  11520.     —>  12  ioCompletion    pointer
  11521.     <—  16  ioResult        word
  11522.     —>  24  ioRefNum        word
  11523.     —>  32  ioBuffer        pointer
  11524.     —>  36  ioReqCount      long word
  11525.     <—  40  ioActCount      long word
  11526.     —>  44  ioPosMode       word
  11527.     <–> 46  ioPosOffset     long word
  11528.  
  11529.     PBWrite takes ioReqCount bytes from the buffer pointed to by
  11530. ioBuffer and attempts to write them to the open file whose access path
  11531. is specified by ioRefNum. The position of the mark is specified by
  11532. ioPosMode and ioPosOffset. After the write is completed, the mark is
  11533. returned in ioPosOffset and the number of bytes actually written is
  11534. returned in ioActCount.
  11535.  
  11536. Result codes    noErr       No error
  11537.                 dskFulErr   Disk full
  11538.                 fLckdErr    File locked
  11539.                 fnOpnErr    File not open
  11540.                 ioErr       I/O error
  11541.                 paramErr    Negative ioReqCount
  11542.                 posErr      Attempt to position before start of file
  11543.                 rfNumErr    Bad reference number
  11544.                 vLckdErr    Software volume lock
  11545.                 wPrErr      Hardware volume lock
  11546.                 wrPermErr   Read/write permission doesn’t allow writing
  11547. \ PBGetFPos
  11548. 17
  11549. FUNCTION PBGetFPos (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr;
  11550.  
  11551. Trap macro  _GetFPos
  11552.  
  11553. Parameter block
  11554.     —>  12  ioCompletion    pointer
  11555.     <—  16  ioResult        word
  11556.     —>  24  ioRefNum        word
  11557.     <—  36  ioReqCount      long word
  11558.     <—  40  ioActCount      long word
  11559.     <—  44  ioPosMode       word
  11560.     <—  46  ioPosOffset     long word
  11561.  
  11562.     PBGetFPos returns, in ioPosOffset, the mark of the open file whose
  11563. access path is specified by ioRefNum. It sets ioReqCount, ioActCount,
  11564. and ioPosMode to 0.
  11565.  
  11566. Result codes    noErr       No error
  11567.                 extFSErr    External file system
  11568.                 fnOpnErr    File not open
  11569.                 gfpErr      Error during GetFPos
  11570.                 ioErr       I/O error
  11571.                 rfNumErr    Bad reference number
  11572. \ PBSetFPos
  11573. 17
  11574. FUNCTION PBSetFPos (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr;
  11575.  
  11576. Trap macro  _SetFPos
  11577.  
  11578. Parameter block
  11579.     —>  12  ioCompletion    pointer
  11580.     <—  16  ioResult        word
  11581.     —>  24  ioRefNum        word
  11582.     —>  44  ioPosMode       word
  11583.     <–> 46  ioPosOffset     long word
  11584.  
  11585.     PBSetFPos sets the mark of the open file whose access path is
  11586. specified by ioRefNum to the position specified by ioPosMode and
  11587. ioPosOffset. The position at which the mark is actually set is returned
  11588. in ioPosOffset. If you try to set the mark past the logical
  11589. end-of-file, PBSetFPos moves the mark to the end-of-file and returns
  11590. eofErr as its function result.
  11591.  
  11592. Result codes    noErr       No error
  11593.                 eofErr      End-of-file
  11594.                 extFSErr    External file system
  11595.                 fnOpnErr    File not open
  11596.                 ioErr       I/O error
  11597.                 posErr      Attempt to position before start of file
  11598.                 rfNumErr    Bad reference number
  11599. \ PBGetEOF
  11600. 17
  11601. FUNCTION PBGetEOF (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr;
  11602.  
  11603. Trap macro  _GetEOF
  11604.  
  11605. Parameter block
  11606.     —>  12  ioCompletion    pointer
  11607.     <—  16  ioResult        word
  11608.     —>  24  ioRefNum        word
  11609.     <—  28  ioMisc          long word
  11610.  
  11611.     PBGetEOF returns, in ioMisc, the logical end-of-file of the open
  11612. file whose access path is specified by ioRefNum.
  11613.  
  11614. Result codes    noErr       No error
  11615.                 extFSErr    External file system
  11616.                 fnOpnErr    File not open
  11617.                 ioErr       I/O error
  11618.                 rfNumErr    Bad reference number
  11619. \ PBSetEOF
  11620. 17
  11621. FUNCTION PBSetEOF (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr;
  11622.  
  11623. Trap macro  _SetEOF
  11624.  
  11625. Parameter block
  11626.     —>  12  ioCompletion    pointer
  11627.     <—  16  ioResult        word
  11628.     —>  24  ioRefNum        word
  11629.     —>  28  ioMisc          long word
  11630.  
  11631.     PBSetEOF sets the logical end-of-file of the open file, whose access
  11632. path is specified by ioRefNum, to ioMisc. If you attempt to set the
  11633. logical end-of-file beyond the physical end-of-file, another allocation
  11634. block is added to the file; if there isn’t enough space on the volume,
  11635. no change is made, and PBSetEOF returns dskFulErr as its function
  11636. result. If ioMisc is 0, all space occupied by the file on the volume is
  11637. released.
  11638.  
  11639. Result codes    noErr       No error
  11640.                 dskFulErr   Disk full
  11641.                 extFSErr    External file system
  11642.                 fLckdErr    File locked
  11643.                 fnOpnErr    File not open
  11644.                 ioErr       I/O error
  11645.                 rfNumErr    Bad reference number
  11646.                 vLckdErr    Software volume lock
  11647.                 wPrErr      Hardware volume lock
  11648.                 wrPermErr   Read/write permission doesn’t allow writing
  11649. \ PBAllocate
  11650. 17
  11651. FUNCTION PBAllocate (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr;
  11652.  
  11653. Trap macro  _Allocate
  11654.  
  11655. Parameter block
  11656.     —>  12  ioCompletion    pointer
  11657.     <—  16  ioResult        word
  11658.     —>  24  ioRefNum        word
  11659.     —>  36  ioReqCount      long word
  11660.     <—  40  ioActCount      long word
  11661.  
  11662.     PBAllocate adds ioReqCount bytes to the open file whose access path
  11663. is specified by ioRefNum, and sets the physical end-of-file to one byte
  11664. beyond the last block allocated. The number of bytes actually allocated
  11665. is rounded up to the nearest multiple of the allocation block size, and
  11666. returned in ioActCount. If there isn’t enough empty space on the volume
  11667. to satisfy the allocation request, PBAllocate allocates the rest of the
  11668. space on the volume and returns dskFulErr as its function result.
  11669.  
  11670. Note:  Even if the total number of requested bytes is unavailable,
  11671.        PBAllocate will allocate whatever space, contiguous or not, is
  11672.        available. To force the allocation of the entire requested space
  11673.        as a contiguous piece, call PBAllocContig instead.
  11674.  
  11675. Result codes    noErr       No error
  11676.                 dskFulErr   Disk full
  11677.                 fLckdErr    File locked
  11678.                 fnOpnErr    File not open
  11679.                 ioErr       I/O error
  11680.                 rfNumErr    Bad reference number
  11681.                 vLckdErr    Software volume lock
  11682.                 wPrErr      Hardware volume lock
  11683.                 wrPermErr   Read/write permission doesn’t allow writing
  11684. \ PBAllocContig
  11685. 17
  11686. FUNCTION PBAllocContig (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr;
  11687.  
  11688. Trap macro  _AllocContig
  11689.  
  11690. Parameter block
  11691.     —>  12  ioCompletion    pointer
  11692.     <—  16  ioResult        word
  11693.     —>  24  ioRefNum        word
  11694.     —>  36  ioReqCount      long word
  11695.     <—  40  ioActCount      long word
  11696.  
  11697.     PBAllocContig is identical to PBAllocate except that if there isn’t
  11698. enough contiguous empty space on the volume to satisfy the allocation
  11699. request, PBAllocContig will do nothing and will return dskFulErr as its
  11700. function result. If you want to allocate whatever space is available,
  11701. even when the entire request cannot be filled as a contiguous piece,
  11702. call PBAllocate instead.
  11703.  
  11704. Result codes    noErr       No error
  11705.                 dskFulErr   Disk full
  11706.                 fLckdErr    File locked
  11707.                 fnOpnErr    File not open
  11708.                 ioErr       I/O error
  11709.                 rfNumErr    Bad reference number
  11710.                 vLckdErr    Software volume lock
  11711.                 wPrErr      Hardware volume lock
  11712.                 wrPermErr   Read/write permission doesn’t allow writing
  11713. \ PBFlushFile
  11714. 17
  11715. FUNCTION PBFlushFile (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr;
  11716.  
  11717. Trap macro  _FlushFile
  11718.  
  11719. Parameter block
  11720.     —>  12  ioCompletion    pointer
  11721.     <—  16  ioResult        word
  11722.     —>  24  ioRefNum        word
  11723.  
  11724.     PBFlushFile writes the contents of the access path buffer indicated
  11725. by ioRefNum to the volume, and updates the file’s entry in the file
  11726. directory (or in the file catalog, in the case of hierarchical volumes).
  11727.  
  11728. Warning:  Some information stored on the volume won’t be correct until
  11729.           PBFlushVol is called.
  11730.  
  11731. Result codes    noErr       No error
  11732.                 extFSErr    External file system
  11733.                 fnfErr      File not found
  11734.                 fnOpnErr    File not open
  11735.                 ioErr       I/O error
  11736.                 nsvErr      No such volume
  11737.                 rfNumErr    Bad reference number
  11738.  
  11739. \ PBClose
  11740. 17
  11741. FUNCTION PBClose (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr;
  11742.  
  11743. Trap macro  _Close
  11744.  
  11745. Parameter block
  11746.     —>  12  ioCompletion    pointer
  11747.     <—  16  ioResult        word
  11748.     —>  24  ioRefNum        word
  11749.  
  11750.     PBClose writes the contents of the access path buffer specified by
  11751. ioRefNum to the volume and removes the access path.
  11752.  
  11753. Warning:  Some information stored on the volume won’t be correct until
  11754.           PBFlushVol is called.
  11755.  
  11756. Result codes    noErr       No error
  11757.                 extFSErr    External file system
  11758.                 fnfErr      File not found
  11759.                 fnOpnErr    File not open
  11760.                 ioErr       I/O error
  11761.                 nsvErr      No such volume
  11762.                 rfNumErr    Bad reference number
  11763.  
  11764. \ PBCreate
  11765. 17
  11766. FUNCTION PBCreate (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr;
  11767.  
  11768. Trap macro  _Create
  11769.  
  11770. Parameter block
  11771.     —>  12  ioCompletion    pointer
  11772.     <—  16  ioResult        word
  11773.     —>  18  ioNamePtr       pointer
  11774.     —>  22  ioVRefNum       word
  11775.     —>  26  ioFVersNum      byte
  11776.  
  11777.     PBCreate creates a new file (both forks) having the name pointed to
  11778. by ioNamePtr (and on flat volumes, the version number ioVersNum) on the
  11779. volume specified by ioVRefNum. The new file is unlocked and empty. The
  11780. date and time of its creation and last modification are set to the
  11781. current date and time. If the file created isn’t temporary (that is, if
  11782. it will exist after the application terminates), the application should
  11783. call PBSetFInfo (after PBCreate) to fill in the information needed by
  11784. the Finder.
  11785. ________________________________________________________________________
  11786.  
  11787. Assembly-language note:  If a desk accessory creates a file, it should
  11788. always create it in the directory containing the system folder. The
  11789. working directory reference number for this directory is stored in the
  11790. global variable BootDrive; you can pass it in ioVRefNum.
  11791. ________________________________________________________________________
  11792.  
  11793. Result codes    noErr       No error
  11794.                 bdNamErr    Bad file name
  11795.                 dupFNErr    Duplicate file name and version
  11796.                 dirFulErr   File directory full
  11797.                 extFSErr    External file system
  11798.                 ioErr       I/O error
  11799.                 nsvErr      No such volume
  11800.                 vLckdErr    Software volume lock
  11801.                 wPrErr      Hardware volume lock
  11802. \ PBHCreate
  11803. 17
  11804. FUNCTION PBHCreate (paramBlock: HParmBlkPtr; async: BOOLEAN) : OSErr;
  11805.  
  11806. Trap macro  _HCreate
  11807.  
  11808. Parameter block
  11809.     —>  12  ioCompletion    pointer
  11810.     <—  16  ioResult        word
  11811.     —>  18  ioNamePtr       pointer
  11812.     —>  22  ioVRefNum       word
  11813.     —>  48  ioDirID         long word
  11814.  
  11815.     PBHCreate is identical to PBCreate except that it accepts a
  11816. directory ID in ioDirID.
  11817.  
  11818. Note:  To create a directory instead of a file, call PBDirCreate.
  11819.  
  11820. Result codes    noErr       No error
  11821.                 bdNamErr    Bad file name
  11822.                 dupFNErr    Duplicate file name and version
  11823.                 dirFulErr   File directory full
  11824.                 dirNFErr    Directory not found or incomplete pathname
  11825.                 extFSErr    External file system
  11826.                 ioErr       I/O error
  11827.                 nsvErr      No such volume
  11828.                 vLckdErr    Software volume lock
  11829.                 wPrErr      Hardware volume lock
  11830. \ PBDirCreate
  11831. 17
  11832. FUNCTION PBDirCreate (paramBlock: HParmBlkPtr; async: BOOLEAN): OSErr;
  11833.  
  11834. Trap macro  _DirCreate
  11835.  
  11836. Parameter block
  11837.     —>  12  ioCompletion    pointer
  11838.     <—  16  ioResult        word
  11839.     <–> 18  ioNamePtr       pointer
  11840.     —>  22  ioVRefNum       word
  11841.     <–> 48  ioDirID         long word
  11842.  
  11843.     PBDirCreate is identical to PBHCreate except that it creates a new
  11844. directory instead of a file. You can specify the parent of the
  11845. directory to be created in ioDirID; if it’s 0, the new directory will be
  11846. placed in the root directory. The directory ID of the new directory is
  11847. returned in ioDirID.
  11848.  
  11849. Warning:  PBDirCreate operates only with the hierarchical version of the
  11850.           File Manager; if used on a Macintosh equipped only with the
  11851.           64K ROM version of the File Manager, it will generate a system
  11852.           error.
  11853.  
  11854. Result codes    noErr       No error
  11855.                 bdNamErr    Bad file name
  11856.                 dupFNErr    Duplicate file name and version
  11857.                 dirFulErr   File directory full
  11858.                 dirNFErr    Directory not found or incomplete pathname
  11859.                 extFSErr    External file system
  11860.                 ioErr       I/O error
  11861.                 nsvErr      No such volume
  11862.                 vLckdErr    Software volume lock
  11863.                 wPrErr      Hardware volume lock
  11864.  
  11865. \ PBDelete
  11866. 17
  11867. FUNCTION PBDelete (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr;
  11868.  
  11869. Trap macro  _Delete
  11870.  
  11871. Parameter block
  11872.     —>  12  ioCompletion    pointer
  11873.     <—  16  ioResult        word
  11874.     —>  18  ioNamePtr       pointer
  11875.     —>  22  ioVRefNum       word
  11876.     —>  26  ioFVersNum      byte
  11877.  
  11878.     PBDelete removes the closed file having the name pointed to by
  11879. ioNamePtr (and on flat volumes, the version number ioVersNum) from the
  11880. volume pointed to by ioVRefNum. PBHDelete can be used to delete an
  11881. empty directory as well.
  11882.  
  11883. Note:  This function will delete both forks of the file.
  11884.  
  11885. Result codes    noErr       No error
  11886.                 bdNamErr    Bad file name
  11887.                 extFSErr    External file system
  11888.                 fBsyErr     File busy, directory not empty, or working
  11889.                             directory control block open
  11890.                 fLckdErr    File locked
  11891.                 fnfErr      File not found
  11892.                 nsvErr      No such volume
  11893.                 ioErr       I/O error
  11894.                 vLckdErr    Software volume lock
  11895.                 wPrErr      Hardware volume lock
  11896. \ PBHDelete
  11897. 17
  11898. FUNCTION PBHDelete (paramBlock: HParmBlkPtr; async: BOOLEAN) : OSErr;
  11899.  
  11900. Trap macro  _HDelete
  11901.  
  11902. Parameter block
  11903.     —>  12  ioCompletion    pointer
  11904.     <—  16  ioResult        word
  11905.     —>  18  ioNamePtr       pointer
  11906.     —>  22  ioVRefNum       word
  11907.     —>  48  ioDirID         long word
  11908.  
  11909.     PBHDelete is identical to PBDelete except that it accepts a
  11910. directory ID in ioDirID. PBHDelete can be used to delete an empty
  11911. directory as well.
  11912.  
  11913. Result codes    noErr       No error
  11914.                 bdNamErr    Bad file name
  11915.                 dirNFErr    Directory not found or incomplete pathname
  11916.                 extFSErr    External file system
  11917.                 fBsyErr     File busy, directory not empty,
  11918.                             or working directory control block open
  11919.                 fLckdErr    File locked
  11920.                 fnfErr      File not found
  11921.                 nsvErr      No such volume
  11922.                 ioErr       I/O error
  11923.                 vLckdErr    Software volume lock
  11924.                 wPrErr      Hardware volume lock
  11925. \ PBGetFInfo
  11926. 17
  11927. FUNCTION PBGetFInfo (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr;
  11928.  
  11929. Trap macro  _GetFileInfo
  11930.  
  11931. Parameter block
  11932.     —>  12  ioCompletion    pointer
  11933.     <—  16  ioResult        word
  11934.     <–> 18  ioNamePtr       pointer
  11935.     —>  22  ioVRefNum       word
  11936.     <—  24  ioFRefNum       word
  11937.     —>  26  ioFVersNum      byte
  11938.     —>  28  ioFDirIndex     word
  11939.     <—  30  ioFlAttrib      byte
  11940.     <—  31  ioFlVersNum     byte
  11941.     <—  32  ioFlFndrInfo    16 bytes
  11942.     <—  48  ioFlNum         long word
  11943.     <—  52  ioFlStBlk       word
  11944.     <—  54  ioFlLgLen       long word
  11945.     <—  58  ioFlPyLen       long word
  11946.     <—  62  ioFlRStBlk      word
  11947.     <—  64  ioFlRLgLen      long word
  11948.     <—  68  ioFlRPyLen      long word
  11949.     <—  72  ioFlCrDat       long word
  11950.     <—  76  ioFlMdDat       long word
  11951.  
  11952.     PBGetFInfo returns information about the specified file. If
  11953. ioFDirIndex is positive, the File Manager returns information about the
  11954. file whose directory index is ioFDirIndex on the volume specified by
  11955. ioVRefNum. (See the section “Data Organization on Volumes” if you’re
  11956. interested in using this method.)
  11957.  
  11958. Note:  If a working directory reference number is specified in
  11959.        ioVRefNum, the File Manager returns information about the file
  11960.        whose directory index is ioFDirIndex in the specified directory.
  11961.  
  11962.     If ioFDirIndex is negative or 0, the File Manager returns
  11963. information about the file having the name pointed to by ioNamePtr (and
  11964. on flat volumes, the version number ioFVersNum) on the volume specified
  11965. by ioVRefNum. If the file is open, the reference number of the first
  11966. access path found is returned in ioFRefNum, and the name of the file is
  11967. returned in ioNamePtr (unless ioNamePtr is NIL).
  11968.  
  11969. Result codes    noErr       No error
  11970.                 bdNamErr    Bad file name
  11971.                 extFSErr    External file system
  11972.                 fnfErr      File not found
  11973.                 ioErr       I/O error
  11974.                 nsvErr      No such volume
  11975.                 paramErr    No default volume
  11976. \ PBHGetFInfo
  11977. 17
  11978. FUNCTION PBHGetFInfo (paramBlock: HParmBlkPtr; async: BOOLEAN) : OSErr;
  11979.  
  11980. Trap macro  _HGetFileInfo
  11981.  
  11982. Parameter block
  11983.     —>  12  ioCompletion    pointer
  11984.     <—  16  ioResult        word
  11985.     <–> 18  ioNamePtr       pointer
  11986.     —>  22  ioVRefNum       word
  11987.     <—  24  ioFRefNum       word
  11988.     —>  28  ioFDirIndex     word
  11989.     <—  30  ioFlAttrib      byte
  11990.     <—  32  ioFlFndrInfo    16 bytes
  11991.     <–> 48  ioDirID         long word
  11992.     <—  52  ioFlStBlk       word
  11993.     <—  54  ioFlLgLen       long word
  11994.     <—  58  ioFlPyLen       long word
  11995.     <—  62  ioFlRStBlk      word
  11996.     <—  64  ioFlRLgLen      long word
  11997.     <—  68  ioFlRPyLen      long word
  11998.     <—  72  ioFlCrDat       long word
  11999.     <—  76  ioFlMdDat       long word
  12000.  
  12001.     PBHGetFInfo is identical to PBGetFInfo except that it accepts a
  12002. directory ID in ioDirID.
  12003.  
  12004. Result codes    noErr       No error
  12005.                 bdNamErr    Bad file name
  12006.                 dirNFErr    Directory not found or incomplete pathname
  12007.                 extFSErr    External file system
  12008.                 fnfErr      File not found
  12009.                 ioErr       I/O error
  12010.                 nsvErr      No such volume
  12011.                 paramErr    No default volume
  12012. \ PBSetFInfo
  12013. 17
  12014. FUNCTION PBSetFInfo (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr;
  12015.  
  12016. Trap macro  _SetFileInfo
  12017.  
  12018. Parameter block
  12019.     —>  12  ioCompletion    pointer
  12020.     <—  16  ioResult        word
  12021.     —>  18  ioNamePtr       pointer
  12022.     —>  22  ioVRefNum       word
  12023.     —>  26  ioFVersNum      byte
  12024.     —>  32  ioFlFndrInfo    16 bytes
  12025.     —>  72  ioFlCrDat       long word
  12026.     —>  76  ioFlMdDat       long word
  12027.  
  12028.     PBSetFInfo sets information (including the date and time of creation
  12029. and modification, and information needed by the Finder) about the file
  12030. having the name pointed to by ioNamePtr (and on flat volumes, the
  12031. version number ioFVersNum) on the volume specified by ioVRefNum. You
  12032. should call PBGetFInfo just before PBSetFInfo, so the current
  12033. information is present in the parameter block.
  12034.  
  12035. Result codes    noErr       No error
  12036.                 bdNamErr    Bad file name
  12037.                 extFSErr    External file system
  12038.                 fLckdErr    File locked
  12039.                 fnfErr      File not found
  12040.                 ioErr       I/O error
  12041.                 nsvErr      No such volume
  12042.                 vLckdErr    Software volume lock
  12043.                 wPrErr      Hardware volume lock
  12044. \ PBHSetFInfo
  12045. 17
  12046. FUNCTION PBHSetFInfo (paramBlock: HParmBlkPtr; async: BOOLEAN) : OSErr;
  12047.  
  12048. Trap macro  _HSetFileInfo
  12049.  
  12050. Parameter block
  12051.     —>  12  ioCompletion    pointer
  12052.     <—  16  ioResult        word
  12053.     —>  18  ioNamePtr       pointer
  12054.     —>  22  ioVRefNum       word
  12055.     —>  32  ioFlFndrInfo    16 bytes
  12056.     —>  48  ioDirID         long word
  12057.     —>  72  ioFlCrDat       long word
  12058.     —>  76  ioFlMdDat       long word
  12059.  
  12060.     PBHSetFInfo is identical to PBSetFInfo except that it accepts a
  12061. directory ID in ioDirID.
  12062.  
  12063. Result codes    noErr       No error
  12064.                 bdNamErr    Bad file name
  12065.                 dirNFErr    Directory not found or incomplete pathname
  12066.                 extFSErr    External file system
  12067.                 fLckdErr    File locked
  12068.                 fnfErr      File not found
  12069.                 ioErr       I/O error
  12070.                 nsvErr      No such volume
  12071.                 vLckdErr    Software volume lock
  12072.                 wPrErr      Hardware volume lock
  12073. \ PBSetFLock
  12074. 17
  12075. FUNCTION PBSetFLock (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr;
  12076.  
  12077. Trap macro  _SetFilLock
  12078.  
  12079. Parameter block
  12080.     —>  12  ioCompletion    pointer
  12081.     <—  16  ioResult        word
  12082.     —>  18  ioNamePtr       pointer
  12083.     —>  22  ioVRefNum       word
  12084.     —>  26  ioFVersNum      byte
  12085.  
  12086.     PBSetFLock locks the file having the name pointed to by ioNamePtr
  12087. (and on flat volumes, the version number ioFVersNum) on the volume
  12088. specified by ioVRefNum. Access paths currently in use aren’t affected.
  12089.  
  12090. Result codes    noErr       No error
  12091.                 extFSErr    External file system
  12092.                 fnfErr      File not found
  12093.                 ioErr       I/O error
  12094.                 nsvErr      No such volume
  12095.                 vLckdErr    Software volume lock
  12096.                 wPrErr      Hardware volume lock
  12097.  
  12098. \ PBHSetFLock
  12099. 17
  12100. FUNCTION PBHSetFLock (paramBlock: HParmBlkPtr; async: BOOLEAN) : OSErr;
  12101.  
  12102. Trap macro  _HSetFLock
  12103.  
  12104. Parameter block
  12105.     —>  12  ioCompletion    pointer
  12106.     <—  16  ioResult        word
  12107.     —>  18  ioNamePtr       pointer
  12108.     —>  22  ioVRefNum       word
  12109.     —>  48  ioDirID         long word
  12110.  
  12111.     PBHSetFLock is identical to PBSetFLock except that it accepts a
  12112. directory ID in ioDirID.
  12113.  
  12114. Result codes    noErr       No error
  12115.                 dirNFErr    Directory not found or incomplete pathname
  12116.                 extFSErr    External file system
  12117.                 fnfErr      File not found
  12118.                 ioErr       I/O error
  12119.                 nsvErr      No such volume
  12120.                 vLckdErr    Software volume lock
  12121.                 wPrErr      Hardware volume lock
  12122. \ PBRstFLock
  12123. 17
  12124. FUNCTION PBRstFLock (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr;
  12125.  
  12126. Trap macro  _RstFilLock
  12127.  
  12128. Parameter block
  12129.     —>  12  ioCompletion    pointer
  12130.     <—  16  ioResult        word
  12131.     —>  18  ioNamePtr       pointer
  12132.     —>  22  ioVRefNum       word
  12133.     —>  26  ioFVersNum      byte
  12134.  
  12135.     PBRstFLock unlocks the file having the name pointed to by ioNamePtr
  12136. (and on flat volumes, the version number ioFVersNum) on the volume
  12137. specified by ioVRefNum. Access paths currently in use aren’t affected.
  12138.  
  12139. Result codes    noErr       No error
  12140.                 extFSErr    External file system
  12141.                 fnfErr      File not found
  12142.                 ioErr       I/O error
  12143.                 nsvErr      No such volume
  12144.                 vLckdErr    Software volume lock
  12145.                 wPrErr      Hardware volume lock
  12146.  
  12147. \ PBHRstFLock
  12148. 17
  12149. FUNCTION PBHRstFLock (paramBlock: HParmBlkPtr; async: BOOLEAN) : OSErr;
  12150.  
  12151. Trap macro  _HRstFLock
  12152.  
  12153. Parameter block
  12154.     —>  12  ioCompletion    pointer
  12155.     <—  16  ioResult        word
  12156.     —>  18  ioNamePtr       pointer
  12157.     —>  22  ioVRefNum       word
  12158.     —>  48  ioDirID         long word
  12159.  
  12160.     PBHRstFLock is identical to PBRstFLock except that it accepts a
  12161. directory ID in ioDirID.
  12162.  
  12163. Result codes    noErr       No error
  12164.                 dirNFErr    Directory not found or incomplete pathname
  12165.                 extFSErr    External file system
  12166.                 fnfErr      File not found
  12167.                 ioErr       I/O error
  12168.                 nsvErr      No such volume
  12169.                 vLckdErr    Software volume lock
  12170.                 wPrErr      Hardware volume lock
  12171.  
  12172. \ PBSetFVers
  12173. 17
  12174. FUNCTION PBSetFVers (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr;
  12175.  
  12176. Trap macro  _SetFilType
  12177.  
  12178. Parameter block
  12179.     —>  12  ioCompletion    pointer
  12180.     <—  16  ioResult        word
  12181.     —>  18  ioNamePtr       pointer
  12182.     —>  22  ioVRefNum       word
  12183.     —>  26  ioVersNum       byte
  12184.     —>  28  ioMisc          byte
  12185.  
  12186.     PBSetFVers has no effect on hierarchical volumes. On flat volumes,
  12187. PBSetFVers changes the version number of the file having the name
  12188. pointed to by ioNamePtr and version number ioVersNum, on the volume
  12189. specified by ioVRefNum, to the version number stored in the high-order
  12190. byte of ioMisc. Access paths currently in use aren’t affected.
  12191.  
  12192. Result codes    noErr           No error
  12193.                 bdNamErr        Bad file name
  12194.                 dupFNErr        Duplicate file name and version
  12195.                 extFSErr        External file system
  12196.                 fLckdErr        File locked
  12197.                 fnfErr          File not found
  12198.                 nsvErr          No such volume
  12199.                 ioErr           I/O error
  12200.                 paramErr        No default volume
  12201.                 vLckdErr        Software volume lock
  12202.                 wPrErr          Hardware volume lock
  12203.                 wrgVolTypErr    Attempt to perform hierarchical
  12204.                                 operation on a flat volume
  12205. \ PBRename
  12206. 17
  12207. FUNCTION PBRename (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr;
  12208.  
  12209. Trap macro  _Rename
  12210.  
  12211. Parameter block
  12212.     —>  12  ioCompletion    pointer
  12213.     <—  16  ioResult        word
  12214.     —>  18  ioNamePtr       pointer
  12215.     —>  22  ioVRefNum       word
  12216.     —>  26  ioVersNum       byte
  12217.     —>  28  ioMisc          pointer
  12218.  
  12219.     Given a pointer to a file name in ioNamePtr (and on flat volumes, a
  12220. version number in ioVersNum), PBRename changes the name of the file to
  12221. the name pointed to by ioMisc. (If the name pointed to by ioNamePtr
  12222. contains one or more colons, so must the name pointed to by ioMisc.)
  12223. Access paths currently in use aren’t affected. Given a pointer to a
  12224. volume name in ioNamePtr or a volume reference number in ioVRefNum, it
  12225. changes the name of the volume to the name pointed to by ioMisc. If a
  12226. volume to be renamed is specified by its volume reference number,
  12227. ioNamePtr can be NIL.
  12228.  
  12229. Warning:  If a volume to be renamed is specified by its volume name, be
  12230.           sure that it ends with a colon, or Rename will consider it a
  12231.           file name.
  12232.  
  12233. Result codes    noErr       No error
  12234.                 bdNamErr    Bad file name
  12235.                 dirFulErr   File directory full
  12236.                 dupFNErr    Duplicate file name and version
  12237.                 extFSErr    External file system
  12238.                 fLckdErr    File locked
  12239.                 fnfErr      File not found
  12240.                 fsRnErr     Problem during rename
  12241.                 ioErr       I/O error
  12242.                 nsvErr      No such volume
  12243.                 paramErr    No default volume
  12244.                 vLckdErr    Software volume lock
  12245.                 wPrErr      Hardware volume lock
  12246. \ PBHRename
  12247. 17
  12248. FUNCTION PBHRename (paramBlock: HParmBlkPtr; async: BOOLEAN) : OSErr;
  12249.  
  12250. Trap macro  _HRename
  12251.  
  12252. Parameter block
  12253.     —>  12  ioCompletion    pointer
  12254.     <—  16  ioResult        word
  12255.     —>  18  ioNamePtr       pointer
  12256.     —>  22  ioVRefNum       word
  12257.     —>  28  ioMisc      pointer
  12258.     —>  48  ioDirID     long word
  12259.  
  12260.     PBHRename is identical to PBRename except that it accepts a
  12261. directory ID in ioDirID and can be used to rename directories as well as
  12262. files and volumes. Given a pointer to the name of a file or directory
  12263. in ioNamePtr, PBHRename changes it to the name pointed to by ioMisc.
  12264. Given a pointer to a volume name in ioNamePtr or a volume reference
  12265. number in ioVRefNum, it changes the name of the volume to the name
  12266. pointed to by ioMisc.
  12267.  
  12268. Warning:  PBHRename cannot be used to change the directory a file is in.
  12269.  
  12270. Result codes    noErr       No error
  12271.                 bdNamErr    Bad file name
  12272.                 dirFulErr   File directory full
  12273.                 dirNFErr    Directory not found or incomplete pathname
  12274.                 dupFNErr    Duplicate file name and version
  12275.                 extFSErr    External file system
  12276.                 fLckdErr    File locked
  12277.                 fnfErr      File not found
  12278.                 fsRnErr     Problem during rename
  12279.                 ioErr       I/O error
  12280.                 nsvErr      No such volume
  12281.                 paramErr    No default volume
  12282.                 vLckdErr    Software volume lock
  12283.                 wPrErr      Hardware volume lock
  12284. \ PBGetCatInfo
  12285. 17
  12286. FUNCTION PBGetCatInfo (paramBlock: CInfoPBPtr; async: BOOLEAN): OSErr;
  12287.  
  12288. Trap macro  _GetCatInfo
  12289.  
  12290. Parameter block
  12291.     Files:                              Directories:
  12292.     —>  12  ioCompletion    pointer —>  12  ioCompletion    pointer
  12293.     <—  16  ioResult        word    <—  16  ioResult        word
  12294.     <–> 18  ioNamePtr       pointer <–> 18  ioNamePtr       pointer
  12295.     —>  22  ioVRefNum       word    —>  22  ioVRefNum       word
  12296.     <—  24  ioFRefNum       word    <—  24  ioFRefNum       word
  12297.     —>  28  ioFDirIndex     word    —>  28  ioFDirIndex     word
  12298.     <—  30  ioFlAttrib      byte    <—  30  ioFlAttrib      byte
  12299.     <—  32  ioFlFndrInfo    16 bytes<—  32  ioDrUsrWds      16 bytes
  12300.     <–> 48  ioDirID         long    <–> 48  ioDrDirID       long
  12301.     <—  52  ioFlStBlk       word    <—  52  ioDrNmFls       word
  12302.     <—  54  ioFlLgLen       long
  12303.     <—  58  ioFlPyLen       long
  12304.     <—  62  ioFlRStBlk      word
  12305.     <—  64  ioFlRLgLen      long
  12306.     <—  68  ioFlRPyLen      long
  12307.     <—  72  ioFlCrDat       long    <—  72  ioDrCrDat       long
  12308.     <—  76  ioFlMdDat       long    <—  76  ioDrMdDat       long
  12309.     <—  80  ioFlBkDat       long    <—  80  ioDrBkDat       long
  12310.     <—  84  ioFlXFndrInfo   16 bytes<—  84  ioDrFndrInfo    16 bytes
  12311.     <—  100 ioFlParID       long    <—  100 ioDrParID       long
  12312.     <—  104 ioFlClpSiz      long
  12313.  
  12314.     PBGetCatInfo gets information about the files and directories in a
  12315. file catalog. To determine whether the information is for a file or a
  12316. directory, test bit 4 of ioFlAttrib, as described in the section
  12317. “CInfoPBRec”. The information that’s returned for files is shown in the
  12318. left column, and the corresponding information for directories is shown
  12319. in the right column.
  12320.  
  12321.     If ioFDirIndex is positive, the File Manager returns information
  12322. about the file or directory whose directory index is ioFDirIndex in the
  12323. directory specified by ioVRefNum (this will be the root directory if a
  12324. volume reference number is provided).
  12325.  
  12326.     If ioFDirIndex is 0, the File Manager returns information about the
  12327. file or directory specified by ioNamePtr, in the directory specified by
  12328. ioVRefNum (again, this will be the root directory if a volume reference
  12329. number is provided).
  12330.  
  12331.     If ioFDirIndex is negative, the File Manager ignores ioNamePtr and
  12332. returns information about the directory specified by ioDirID.
  12333.  
  12334.     With files, PBGetCatInfo is similar to PBHGetFileInfo but returns
  12335. some additional information. If the file is open, the reference number
  12336. of the first access path found is returned in ioFRefNum, and the name of
  12337. the file is returned in ioNamePtr (unless ioNamePtr is NIL).
  12338.  
  12339. Result codes    noErr       No error
  12340.                 bdNamErr    Bad file name
  12341.                 dirNFErr    Directory not found or incomplete pathname
  12342.                 extFSErr    External file system
  12343.                 fnfErr      File not found
  12344.                 ioErr       I/O error
  12345.                 nsvErr      No such volume
  12346.                 paramErr    No default volume
  12347. \ PBSetCatInfo
  12348. 17
  12349. FUNCTION PBSetCatInfo (paramBlock: CInfoPBPtr; async: BOOLEAN) : OSErr;
  12350.  
  12351. Trap macro  _SetCatInfo
  12352.  
  12353. Parameter block
  12354.     Files:                          Directories:
  12355.     —>  12  ioCompletion    pointer —>  12  ioCompletion    pointer
  12356.     <—  16  ioResult        word    <—  16  ioResult        word
  12357.     <–> 18  ioNamePtr       pointer <–> 18  ioNamePtr       pointer
  12358.     —>  22  ioVRefNum       word    —>  22  ioVRefNum       word
  12359.     —>  30  ioFlAttrib      byte    —>  30  ioFlAttrib      byte
  12360.     —>  32  ioFlFndrInfo    16 bytes—>  32  ioDrUsrWds      16 bytes
  12361.     —>  48  ioDirID         long    —>  48  ioDrDirID       long
  12362.     —>  72  ioFlCrDat       long    —>  72  ioDrCrDat       long
  12363.     —>  76  ioFlMdDat       long    —>  76  ioDrMdDat       long
  12364.     —>  80  ioFlBkDat       long    —>  80  ioDrBkDat       long
  12365.     —>  84  ioFlXFndrInfo   16 bytes—>  84  ioDrFndrInfo    16 bytes
  12366.     —>  104 ioFlClpSiz      long
  12367.  
  12368.     PBSetCatInfo sets information about the files and directories in a
  12369. catalog. With files, it’s similar to PBHSetFileInfo but lets you set
  12370. some additional information. The information that can be set for files
  12371. is shown in the left column, and the corresponding information for
  12372. directories is shown in the right column.
  12373.  
  12374. Result codes    noErr       No error
  12375.                 bdNamErr    Bad file name
  12376.                 dirNFErr    Directory not found or incomplete pathname
  12377.                 extFSErr    External file system
  12378.                 fnfErr      File not found
  12379.                 ioErr       I/O error
  12380.                 nsvErr      No such volume
  12381.                 paramErr    No default volume
  12382. \ PBCatMove
  12383. 17
  12384. FUNCTION PBCatMove (paramBlock: CMovePBPtr; async: BOOLEAN) : OSErr;
  12385.  
  12386. Trap macro  _CatMove
  12387.  
  12388. Parameter block
  12389.     —>  12  ioCompletion    pointer
  12390.     <—  16  ioResult        word
  12391.     —>  18  ioNamePtr       pointer
  12392.     —>  22  ioVRefNum       word
  12393.     —>  28  ioNewName       pointer
  12394.     —>  36  ioNewDirID      long word
  12395.     —>  48  ioDirID         long word
  12396.  
  12397.     PBCatMove moves files or directories from one directory to another.
  12398. The name of the file or directory to be moved is pointed to by
  12399. ioNamePtr; ioVRefNum contains either the volume reference number or
  12400. working directory reference number. A directory ID can be specified in
  12401. ioDirID. The name and directory ID of the directory to which the file
  12402. or directory is to be moved are specified by ioNewName and ioNewDirID.
  12403.  
  12404.     PBCatMove is strictly a file catalog operation; it does not actually
  12405. change the location of the file or directory on the disk. PBCatMove
  12406. cannot move a file or directory to another volume (that is, ioVRefNum is
  12407. used in specifying both the source and the destination). It also cannot
  12408. be used to rename files or directories; for that, use PBHRename.
  12409.  
  12410. Result codes    noErr       No error
  12411.                 badMovErr   Attempt to move into offspring
  12412.                 bdNamErr    Bad file name or attempt to move into a file
  12413.                 dupFNErr    Duplicate file name and version
  12414.                 fnfErr      File not found
  12415.                 ioErr       I/O error
  12416.                 nsvErr      No such volume
  12417.                 paramErr    No default volume
  12418.                 vLckdErr    Software volume lock
  12419.                 wPrErr      Hardware volume lock
  12420. \ PBOpenWD
  12421. 17
  12422. FUNCTION PBOpenWD (paramBlock: WDPBPtr; async: BOOLEAN) : OSErr;
  12423.  
  12424. Trap macro  _OpenWD
  12425.  
  12426. Parameter block
  12427.     —>  12  ioCompletion    pointer
  12428.     <—  16  ioResult        word
  12429.     —>  18  ioNamePtr       pointer
  12430.     <–> 22  ioVRefNum       word
  12431.     —>  28  ioWDProcID      long word
  12432.     —>  48  ioWDDirID       long word
  12433.  
  12434.     PBOpenWD takes the directory specified by ioVRefNum, ioWDDirID, and
  12435. ioWDProcID and makes it a working directory. (You can also specify the
  12436. directory using a combination of partial pathname and directory ID.)  It
  12437. returns a working directory reference number in ioVRefNum that can be
  12438. used in subsequent calls.
  12439.  
  12440.     If a given directory has already been made a working directory using
  12441. the same ioWDProcID, no new working directory will be opened; instead,
  12442. the existing working directory reference number will be returned. If a
  12443. given directory was already made a working directory using a different
  12444. ioWDProcID, a new working directory reference number is returned.
  12445.  
  12446. Result codes    noErr       No error
  12447.                 tmwdoErr    Too many working directories open
  12448. \ PBCloseWD
  12449. 17
  12450. FUNCTION PBCloseWD (paramBlock: WDPBPtr; async: BOOLEAN) : OSErr;
  12451.  
  12452. Trap macro  _CloseWD
  12453.  
  12454. Parameter block
  12455.     —>  12  ioCompletion    pointer
  12456.     <—  16  ioResult        word
  12457.     —>  22  ioVRefNum       word
  12458.  
  12459.     PBCloseWD releases the working directory whose working directory
  12460. reference number is specified in ioVRefNum.
  12461.  
  12462. Note:  If a volume reference number is specified in ioVRefNum, PBCloseWD
  12463.        does nothing.
  12464.  
  12465. Result codes    noErr   No error
  12466.                 nsvErr  No such volume
  12467. \ PBGetWDInfo
  12468. 17
  12469. FUNCTION PBGetWDInfo (paramBlock: WDPBPtr; async: BOOLEAN) : OSErr;
  12470.  
  12471. Trap macro  _GetWDInfo
  12472.  
  12473. Parameter block
  12474.     —>  12  ioCompletion    pointer
  12475.     <—  16  ioResult        word
  12476.     <—  18  ioNamePtr       pointer
  12477.     <–> 22  ioVRefNum       word
  12478.     —>  26  ioWDIndex       word
  12479.     <–> 28  ioWDProcID      long word
  12480.     <–> 32  ioWDVRefNum     word
  12481.     <—  48  ioWDDirID       long word
  12482.  
  12483.     PBGetWDInfo returns information about the specified working
  12484. directory. The working directory can be specified either by its working
  12485. directory reference number in ioVRefNum (in which case ioWDIndex should
  12486. be 0), or by its index number in ioWDIndex. In the latter case, if
  12487. ioVRefNum is nonzero, it’s interpreted as a volume specification (volume
  12488. reference number or drive number), and only working directories on that
  12489. volume are indexed.
  12490.  
  12491.     IOWDVRefNum always returns the volume reference number. IOVRefNum
  12492. returns a working directory reference number when a working directory
  12493. reference number is passed in that field; otherwise, it returns a volume
  12494. reference number. The volume name is returned in ioNamePtr.
  12495.  
  12496.     If IOWDProcID is nonzero, only working directories with that
  12497. identifier are indexed; otherwise all working directories are indexed.
  12498.  
  12499. Result codes    noErr   No error
  12500.                 nsvErr  No such volume
  12501. \ PrOpen
  12502. 18
  12503. PROCEDURE PrOpen;
  12504.  
  12505.     PrOpen prepares the Printing Manager for use. It opens the Printer
  12506. Driver and the printer resource file. If either of these items is
  12507. missing, or if the printer resource file is not properly formed, PrOpen
  12508. will do nothing, and PrError will return a Resource Manager result
  12509. code.
  12510. \ PrClose
  12511. 18
  12512. PROCEDURE PrClose;
  12513.  
  12514.     PrClose releases the memory used by the Printing Manager. It closes
  12515. the printer resource file, allowing the file's resource map to be
  12516. removed from memory. It *** currently *** doesn't close the Printer
  12517. Driver, however, since the driver may have been opened before the
  12518. PrOpen call was issued.
  12519. \ PrintDefault
  12520. 18
  12521. PROCEDURE PrintDefault (hPrint: THPrint);
  12522.  
  12523.     PrintDefault fills the fields of a print record with the current
  12524. default values stored in the printer resource file. HPrint is a handle
  12525. to the record, which may be a new print record that you've just
  12526. allocated or an existing one (from a document, for example).
  12527. \ PrValidate
  12528. 18
  12529. FUNCTION PrValidate (hPrint: THPrint) : BOOLEAN;
  12530.  
  12531.     PrValidate checks the contents of a print record for compatibility
  12532. with the current version of the Printing Manager and with the installed
  12533. printer. If the record is valid, the function returns FALSE (no
  12534. change); if invalid, the record is adjusted to the current default
  12535. values, taken from the printer resource file, and the function returns
  12536. TRUE.
  12537.  
  12538.     PrValidate also updates the print record to reflect the current
  12539. settings in the style and job subrecords. These changes have no effect
  12540. on the function's Boolean result.
  12541. \ PrStlDialog
  12542. 18
  12543. FUNCTION PrStlDialog (hPring: THPrint) : BOOLEAN;
  12544.  
  12545.     PrStlDialog conducts a style dialog with the user to determine the
  12546. paper size and paper orientation being used. The initial settings
  12547. displayed in the dialog box are taken from the current values in the
  12548. print record. If the user confirms the dialog, the results of the
  12549. dialog are saved in the print record and the function returns TRUE;
  12550. otherwise the print record is left unchanged and the function returns
  12551. FALSE.
  12552.  
  12553. (note)
  12554.     If the print record was taken from a document, you should
  12555.     update its contents in the document's file if PrStlDialog
  12556.     returns TRUE. This makes the results of the style dialog
  12557.     "stick" to the document.
  12558. \ PrJobDialog
  12559. 18
  12560. FULNCTION PrJobDialog (hPrint: THPrint) : BOOLEAN;
  12561.  
  12562.     PrJobDialog conducts a job dialog with the user to determine the
  12563. printing quality, number of pages to print, and so on. The initial
  12564. settings displayed in the dialog box are taken from the current values
  12565. in the print reord. If the user confirms the dialog, both the print
  12566. record and the printer resource file are updated (so that the user's
  12567. choices "stick" to the printer) and the function returns TRUE;
  12568. otherwise the print record and printer resource file are left unchanged
  12569. and the function returns FALSE.
  12570.  
  12571. (note)
  12572.     If the job dialog is associated with your application's
  12573.     Print command, you should proceed with the requested
  12574.     printing operation id PrJobDialog returns TRUE. If the
  12575.     print record was taken form a document, you should update
  12576.     its contents in the document's file.
  12577. \ PrJobMerge
  12578. 18
  12579. PROCEDURE PrJobMerge (hPringSrc,hPrintDst: THPrint):
  12580.  
  12581.     PrJobMerge copies the job subrecord from one print record
  12582. (hPrintSrc) to another (hPrintDst) and updates the destination record's
  12583. printer information, band information, and paper rectangle, based on
  12584. information in the job subrecord. This allows the information in the
  12585. job subrecord to be used for a group of related jobs.
  12586. \ PrOpenDoc
  12587. 18
  12588. FUNCTION PrOpenDoc (hPrint: THPrint; pPrPort: TPPrPort; pIOBuf: Ptr)
  12589.         : TPPrPort;
  12590.  
  12591.     PrOpenDoc initializes a printing port for use in printing a document
  12592. makes it the current port, and returns pointer to it. HPrint is a
  12593. handle to the print record for this printing operation. The printing
  12594. port is customized for draft printing or spooling, depending on the
  12595. setting of th bJDocLoop field in the job subrecord. For spooling, the
  12596. spool file's name, volume reference number, and version number are
  12597. taken from the job subrecord.
  12598.  
  12599.     PPrPort is a pointer to the storage to be used for the printing
  12600. port. If this parameter is NIL, PrOpenDoc will allocate a new printing
  12601. port for you. Similarly, pIOBuf points to an area of memory to be used
  12602. as an input/output buffer; if it's NIL, PrOpenDoc will use the volume
  12603. buffer for the spool file's volume.
  12604.  
  12605. (note)
  12606.     The pPrPort and pIOBuf parameters are provided because
  12607.     both the printing port and the input/output buffer are
  12608.     nonrelocatable objects. To avoid cluttering the heap
  12609.     with such objects, you have the opportunity to allocate
  12610.     them yourself and pass them to PrOpenDoc. Most of the
  12611.     time you'll just set both of these parameters to NIL.
  12612.  
  12613. (note)
  12614.     Newly created printing ports use the system font (since
  12615.     they're grafPorts), but newly created windows use the
  12616.     application font. Be sure the font you use in the
  12617.     printing port is the same as the font in your application
  12618.     window if yuou want the text in both places to match.
  12619. \ PrOpenPage
  12620. 18
  12621. PROCEDURE PrOpenPage (pPrPort: TPPrPort; pPageFrame: TPRect);
  12622.  
  12623.     PrOpenPage begins a new page in the document associated with the
  12624. given printing port. The page is printed only if it falls within the
  12625. page range designated in the job subrecord.
  12626.  
  12627.     For spooling, the pPageFrame parameter points to a rectangle that
  12628. will be used as the QuickDraw picture frame for this page:
  12629.  
  12630.     TYPE TPRect = ^Rect;
  12631.  
  12632.     When the spool file is later printed, this rectangle will be scaled
  12633. (via the QuickDraw DrawPicture procedure) to coincide with the page
  12634. rectangle in the printer ilnformation subrecord. Unless you want the
  12635. printout to be scaled, you should set pPageFrame to NIL--this uses the
  12636. curret page rectangle as the picture frame, and the page will be
  12637. printed with no scaling.
  12638. \ PrClosePage
  12639. 18
  12640. PROCEDURE PrClosePage (pPrPort: TPPrPort);
  12641.  
  12642.     PrClosePage finishes up the current page of the document associated
  12643. with the given printing port. For draft printing, it ejects the page
  12644. from the printer and, if necessary, alerts the user to insert another;
  12645. for spooling, it closes the picture representing the current page.
  12646. \ PrCloseDoc
  12647. 18
  12648. PROCEDURE PrCloseDoc (pPrPort: TPPrPort);
  12649.  
  12650.     PrCloseDoc finishes up the printing of the document associated with
  12651. the given printing port. For draft printing, it issues a form feed and
  12652. a reset command to the printer; for spooling, it closes the file if the
  12653. spooling was successfully completed or deletes it the file if the
  12654. spooling was unsuccessful.
  12655. \ PrPicFile
  12656. 18
  12657. PROCEDURE PrPicFile (hPrint: THPrint; pPrPort: TPPrPort; pIOBuf: Ptr;
  12658.         pDevBuf: Ptr; VAR prStatus: TPrStatus);
  12659.  
  12660.     PrPicFile images and prints a spool file. HPrint is a handle to the
  12661. print record for this printing operation. The name, volume reference
  12662. number, and version number of the spool file will be taken from the job
  12663. subrecord of this print record. After printing is successfully
  12664. completed, the Printing Manager deletes the spool file from the disk.
  12665.  
  12666.     PPrPort is a pointer to the storage to be used for the printing port
  12667. for this operation. If this parameter is NIL, PrPicFile will allocate
  12668. its own printing port. Similarly, pIOBuf points to an area of memory
  12669. to be used as an input/output buffer for reading the spool file; if
  12670. it's NIL, PrPicFile will use the volume buffer for the spool file's
  12671. volume. PDevBuf points to a similar buffer (the "band buffer") for
  12672. holding the bit image to be printed; ifNIL, PrPicFile will allocate
  12673. its own buffer from the heap. As for PrOpenDoc, you'll normally want
  12674. to set all of these storage parameters to NIL.
  12675.  
  12676. (note)
  12677.     If you provide your own storage for pDevBuf, it has to be
  12678.     big enough to hold the number of bytes indicated by the
  12679.     iDevBytes field of the TPrXInfo subrecord of the print
  12680.     record.
  12681.  
  12682. (warning)
  12683.     Be sure not to pass, in pPrPort, a pointer to the same
  12684.     printing port you received from PrOpenDoc, the one you
  12685.     originally used to spool the file. If that earlier port
  12686.     was allocated by PrOpenDoc itself (that is, if the
  12687.     pPrPort parameter to PrOpenDoc was NIL), then PrCloseDoc
  12688.     will have disposed of the port, making your pointer to it
  12689.     invalid. PrPicFile initializes a fresh printing port of
  12690.     its own; you just provide the storage (or let PrPicFIle
  12691.     allocate it for itself). Of course, if you earlier
  12692.     provided your own storage to PrOpenDoc, there's no reason
  12693.     you can't use the same storage again for PrPicFile.
  12694.  
  12695.     The prStatus parameter is a printer status record that PrPicFile
  12696. will use to report on its progress. Your background procedure (if any)
  12697. can use this record to monitor the state of the printing operation.
  12698. \ PrError
  12699. 18
  12700. FUNCTION PrError : INTEGER; [Pascal only]
  12701.  
  12702.     PrError returns the result code returned by the last Printing
  12703. Manager routine. The possible result codes are:
  12704.  
  12705.     CONST noErr       = 0;     {no error}
  12706.           iMemFullErr = -108;  {not enough heap space}
  12707.  
  12708.     and any Resource Manager result code. A result code of iMemFullErr
  12709. means that the Memory Manager was unable to fulfill a memory allocation
  12710. request by the Printing Manager.
  12711. \ PrSetError
  12712. 18
  12713. PROCEDURE PrSetError (iErr: INTEGER); [Pascal Only]
  12714.  
  12715.     PrSetError stores the specified value into the global variable where
  12716. the Printing Manager keeps its result code. The main *** (currently
  12717. the only) *** use of this procedure is for canceling a printing
  12718. operation in progress. To do this, write
  12719.  
  12720.     PrSetError(iPrAbort)
  12721.  
  12722. where iPrAbort is the following predefined constant:
  12723.  
  12724.     CONST iPrAbort = 128;  {result code for halting printing}
  12725. \ PrDrvrOpen
  12726. 18
  12727. PROCEDURE PrDrvrOpen;
  12728.  
  12729.     PrDrvrOpen opens the Printer Driver.
  12730. \ PrDrvrClose
  12731. 18
  12732. PROCEDURE PrDrvrClose;
  12733.  
  12734.     PrDrvrClose closes the Printer Driver.
  12735. \ PrCtlCall
  12736. 18
  12737. PROCEDURE PrCtlCall (iWhichCtl: INTEGER; lParam1,lParam2,lParam3):
  12738.                     LongInt);
  12739.  
  12740.     PrCtlCall calls the Printer Driver's control routine. IWhichCtl
  12741. designates the operation to be performed; the rest of the parameters
  12742. depend on the operation.
  12743. \ PrDrvrDCE
  12744. 18
  12745. FUNCTION PrDrvrDCE : Handle;
  12746.  
  12747.     PrDrvrDCE returns a handle to the Printer Driver's device control
  12748. entry.
  12749. \ PrDrvrVers
  12750. 18
  12751. FUNCTION PrDrvrVers : INTEGER;
  12752.  
  12753.     PrDrvrVers returns the version number of the Printer Driver in the
  12754. system resource file.
  12755.  
  12756.     The version number of the Printing Manager is available as the
  12757. predefined constant iPrRelease. You may want to compare the result of
  12758. PrDrvrVers with iPrRelease to see if the Printer Driver in the resource
  12759. file is the most recent version.
  12760. \ PrNoPurge
  12761. 18
  12762. PROCEDURE PrNoPurge;
  12763.  
  12764.     PrNoPurge prevents the Printer Driver from being purged from the
  12765. heap.
  12766. \ PrPurge
  12767. 18
  12768. PROCEDURE PrPurge;
  12769.  
  12770.     PrPurge allows the Printer Driver to be purged from the heap.
  12771. \ OpenDriver
  12772. 19
  12773. FUNCTION OpenDriver (name: Str255; VAR refNum: INTEGER) : OSErr;
  12774.  
  12775.     OpenDriver opens the device driver specified by name and returns its
  12776. reference number in refNum.
  12777.  
  12778.     Result codes    noErr           No error
  12779.                     badUnitErr      Bad reference number
  12780.                     dInstErr        Couldn't find driver in resource
  12781.                                     file
  12782.                     openErr         Driver cannot perform the
  12783.                                     requested reading or writing
  12784.                     unitEmptyErr    Bad reference number
  12785. \ CloseDriver
  12786. 19
  12787. FUNCTION CloseDriver (refNum: INTEGER) : OSErr;
  12788.  
  12789.     CloseDriver closes the device driver having the reference number
  12790. refNum. Any pending I/O is completed, and the memory used by the
  12791. driver is released.
  12792.  
  12793.  
  12794.     Result codes    noErr           No error
  12795.                     badUnitErr      Bad reference number
  12796.                     dRemoveErr      Tried to remove an open driver
  12797.                     unitEmptyErr    Bad reference number
  12798. \ FSRead
  12799. 19
  12800. FUNCTION FSRead (refNum: INTEGER; VARcount: LongInt; buffPtr: Ptr) :
  12801.         OSErr;
  12802.  
  12803.     FSRead attempts to read the number of bytes specified by the count
  12804. parameter from the device driver having the reference number refNum,
  12805. and transfer them to the data buffer pointed to by buffPtr. After the
  12806. read operation is completed, the number of bytes actually read is
  12807. returned in the count parameter.
  12808.  
  12809.  
  12810.     Result codes    noErr           No error
  12811.                     badUnitErr      Bad reference number
  12812.                     notOpenErr      Driver isn't open
  12813.                     unitEmptyErr    Bad reference number
  12814.                     readErr         Driver can't respond to Read
  12815.                                     calls
  12816. \ FSWrite
  12817. 19
  12818. FUNCTION FSWrite (refNum: INTEGR; VARcount: LongInt; buffPtr: Ptr) :
  12819.                     OSErr;
  12820.  
  12821.     FSWrite attempts to take the number of bytes specified by the count
  12822. parameter from the buffer pointed to by buffPtr and write them to the
  12823. open device driver having the reference number refNum. After the write
  12824. operation is completed, the number of bytes actually written is
  12825. returned in the count parameter.
  12826.  
  12827.     Result codes    noErr           No error
  12828.                     badUnitErr      Bad reference number
  12829.                     notOpenErr      Driver isn't open
  12830.                     unitEmptyErr    Bad reference number
  12831.                     writErr         Driver can't respond to Write
  12832.                                     calls
  12833. \ Control
  12834. 19
  12835. FUNCTION COntrol (refNum: INTEGER; csCode: INTEGER; csParam: Ptr):
  12836.         OSErr;
  12837.  
  12838.     Control sends control information to the device driver haaving the
  12839. reference number refNum. The type of information sent is specified by
  12840. csCode, and the ilnformation itself is pointed to by csParam. The
  12841. values passed in csCode and pointed to by csParam depend on the driver
  12842. being called.
  12843.  
  12844.  
  12845.     Result codes    noErr           No error
  12846.                     badUnitErr      Bad reference number
  12847.                     notOpenErr      Driver isn't open
  12848.                     unitEmptyErr    Bad reference number
  12849.                     controlErr      Driver can't respond to this
  12850.                                     Control call
  12851.  
  12852.  
  12853.  
  12854. \ Status
  12855. 19
  12856. FUNCTION Status (refNum: INTEGER; csCode: INTEGER; csParam: Ptr) :
  12857.         OSErr;
  12858.  
  12859.     Status returns status information about the device driver having the
  12860. reference number refNum. The type of information returned is specified
  12861. by csCode, and the information itself is pointed to by csParam. The
  12862. values passed in csCode and pointed to by csParam depend on the driver
  12863. being called.
  12864.  
  12865.     Result codes    noErr           No error
  12866.                     badUnitErr      Bad reference number
  12867.                     notOpenErr      Driver isn't open
  12868.                     unitEmptyErr    Bad reference number
  12869.                     statusErr       Driver can't respond to this
  12870.                                     Status call
  12871. \ KillIO
  12872. 19
  12873. FUNCTION KillIO (refNum: INTEGER) : OSErr;
  12874.  
  12875.     KillIO terminates all current and pending I/O with the device driver
  12876. having the reference number refNum.
  12877.  
  12878.     Result codes    noErr           No error
  12879.                     badUnitErr      Bad reference number
  12880.                     unitEmptyErr    Bad reference number
  12881.                     controlErr      Driver can't respond to KillIO
  12882.                                     calls
  12883.  
  12884. (note)
  12885.     KillIO is actually a special type of PBControl call, and
  12886.     all information aabout PBControl calls applies equally to
  12887.     KillIO.
  12888. \ PBOpen
  12889. 19
  12890. FUNCTION PBOpen (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr;
  12891.  
  12892.     Trap macro  _Open
  12893.  
  12894.     Parameter block
  12895.         --> 12  ioCompletion    pointer
  12896.         <-- 16  ioResult    word
  12897.         --> 18  ioNamePtr   pointer
  12898.         <-- 24  ioRefNum    word
  12899.         --> 27  ioPermssn   byte
  12900.  
  12901.     Result codes    noErr           No error
  12902.                     badUnitErr      Bad reference number
  12903.                     dInstErr        Couldn't find driver in resource
  12904.                                     file
  12905.                     openErr         Driver cannot perform the
  12906.                                     requested reading or writing
  12907.                     unitEmptyErr    Bad reference number
  12908.  
  12909.  
  12910.     PBOpen opens the device driver specified by ioNamePtr and returns
  12911. its reference number in ioRefNum. IOPermssn specifies the requested
  12912. read/write permission.
  12913. \ PBClose
  12914. 19
  12915. FUNCTION PBCLose (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr;
  12916.  
  12917.     Trap macro  _Close
  12918.  
  12919.     Parameter block
  12920.         --> 12  ioCompletion    pointer
  12921.         <-- 16  ioResult    word
  12922.         --> 24  ioRefNum    word
  12923.  
  12924.     Result codes    noErr           No error
  12925.                     badUnitErr      Bad reference number
  12926.                     dRemoveErr      Tried to remove an open driver
  12927.                     unitEmptyErr    Bad reference number
  12928.  
  12929.  
  12930.     PBClose closes the device driver having the reference number
  12931. ioRefNum. Any pending I/O is completed, and the memory used by the
  12932. driver is released.
  12933. \ PBRead
  12934. 19
  12935. FUNCTION PBRead (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr;
  12936.  
  12937.     Trap macro  _Read
  12938.  
  12939.     Parameter block
  12940.         --> 12  ioCompletion    pointer
  12941.         <-- 16  ioResult    word
  12942.         --> 24  ioRefNum    word
  12943.         --> 32  ioBuffer    pointer
  12944.         --> 36  ioReqCount  long word
  12945.         <-- 40  ioActCount  long word
  12946.         --> 44  ioPosMode   word
  12947.         <-> 46  ioPosOffset long word
  12948.  
  12949.  
  12950.  
  12951.  
  12952.     Result codes    noErr           No error
  12953.                     badUnitErr      Bad reference number
  12954.                     notOpenErr      Driver isn't open
  12955.                     unitEmptyErr    Bad reference number
  12956.                     readErr         Driver can't respond to Read
  12957.                                     calls
  12958.  
  12959.     PBRead attempts to read ioReqCount bytes from the device driver
  12960. having the reference number ioRefNum, and transfer them to the data
  12961. buffer pointed to by ioBuffer. After the read operation is completed,
  12962. the number of bytes actually read is returned in ioActCount.
  12963.  
  12964. Advanced programmers:  If the driver is reading from a block device,
  12965.                        the byte offset from the position indicated by
  12966.                        ioPosMode, where the read should actually betwin,
  12967.                        is given by ioPosOffset.
  12968. \ PBWrite
  12969. 19
  12970. FUNCTION PBWrite (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr;
  12971.  
  12972.     Trap macro  _Write
  12973.  
  12974.     Parameter block
  12975.         --> 12  ioCompletion    pointer
  12976.         <-- 16  ioResult    word
  12977.         --> 24  ioRefNum    word
  12978.         --> 32  ioBuffer    pointer
  12979.         --> 36  ioReqCount  long word
  12980.         <-- 40  ioActCount  long word
  12981.         --> 44  ioPosMode   word
  12982.         --> 46  ioPosOffset long word
  12983.  
  12984.     Result codes    noErr       No error
  12985.             badUnitErr  Bad reference number
  12986.             notOpenErr  Driver isn't open
  12987.             unitEmptyErr    Bad reference number
  12988.             writErr Driver  can't respond to Write
  12989.                     calls
  12990.  
  12991.     PBWrite attempts to take ioReqCount bytes from the buffer pointed to
  12992. by ioBuffer and write them to the device driver having the reference
  12993. number ioRefNum. After the write operation is completed, the number of
  12994. bytes actually written is returned in ioActCount.
  12995.  
  12996. Advanced programmers:  If the driver is writing to a block device,
  12997.                        ioPosMode indicates whether the write should
  12998.                        begin relative to the beginning of the device or
  12999.                        the current position. The byte offset from the
  13000.                        position indicated by ioPosMode, where the write
  13001.                        should actually begin, is given by ioPosOffset.
  13002. \ PBControl
  13003. 19
  13004. FUNCTION PBControl (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr;
  13005.  
  13006.     Trap macro  _Control
  13007.  
  13008.     Parameter block
  13009.         --> 12  ioCompletion    pointer
  13010.         <-- 16  ioResult    word
  13011.         --> 24  ioRefNum    word
  13012.         --> 26  csCode      word
  13013.         --> 28  csParam     record
  13014.  
  13015.     Result codes    noErr           No error
  13016.                     badUnitErr      Bad reference number
  13017.                     notOpenErr      Driver isn't open
  13018.                     unitEmptyErr    Bad reference number
  13019.                     controlErr      Driver can't respond to this
  13020.                                     Control call
  13021.  
  13022.  
  13023.     PBControl sends control information to the device driver having the
  13024. reference number ioRefNum. The type of information sent is specified
  13025. by csCode, and the information itself begins at csParam. The values
  13026. passed in csCode and csParam depend on the driver being called.
  13027. \ PBStatus
  13028. 19
  13029. FUNCTION PBStatus (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr;
  13030.  
  13031.     Trap macro  _Status
  13032.  
  13033.     Parameter block
  13034.         --> 12  ioCompletion    pointer
  13035.         <-- 16  ioResult    word
  13036.         --> 24  ioRefNum    word
  13037.         --> 26  csCode      word
  13038.         --> 28  csParam     record
  13039.  
  13040.     Result codes    noErr       No error
  13041.             badUnitErr  Bad reference number
  13042.             notOpenErr  Driver isn't open
  13043.             unitEmptyErr    Bad reference number
  13044.             statusErr   Driver can't respond to this
  13045.                     Status call
  13046.  
  13047.     PBStatus returns status information about the device driver having
  13048. the reference number ioRefNum. The type of information returned is
  13049. specified by csCode, and the information itself begins at csParam. The
  13050. values passed in csCode and csParam depend on the driver being called.
  13051. \ PBKillIO
  13052. 19
  13053. FUNCTION PBKillIO (paramBlock: ParmBlkPtr; async: BOOLEAN) : OSErr;
  13054.  
  13055.     Trap macro  _KillIO
  13056.  
  13057.     Parameter block
  13058.         --> 12  ioCompletion    pointer
  13059.         <-- 16  ioResult    word
  13060.         --> 24  ioRefNum    word
  13061.  
  13062.     Result codes    noErr       No error
  13063.             badUnitErr  Bad reference number
  13064.             unitEmptyErr    Bad reference number
  13065.             controlErr  Driver can't respond to KillIO
  13066.                     calls
  13067.  
  13068.     KillIO stops any current I/O request being processed, and removes
  13069. all pending I/O requests from the I/O queue of the device driver having
  13070. the reference number ioRefNum. The completion routine of each pending
  13071. I/O request is called, with ioResult equal to the following result code:
  13072.  
  13073.     CONST abortErr = -27;
  13074.  
  13075. (note)
  13076.     KillIO is actually a special type of Control call, and
  13077.     all information about Control calls applies equally to
  13078.     KillIO.
  13079. \ DiskEject
  13080. 20
  13081. FUNCTION DiskEject (drvNum: INTEGER) : OSErr;
  13082.  
  13083.     __________________________________________________________________
  13084.  
  13085.     Assembly-language note: DiskEject is equivalent to a Control
  13086.     call with csCode equivalent to the global constant ejectCode.
  13087.     __________________________________________________________________
  13088.  
  13089.     DiskEject ejects the disk from the internal drive if drvNum is 1, or
  13090. from the external drive if drvNum is 2.
  13091.  
  13092.     Result codes
  13093.  
  13094.             noErr       No error
  13095.             nsDrvErr    No such drive
  13096. \ SetTagBuffer
  13097. 20
  13098. FUNCTION SetTagBuffer (buffPtr: Ptr) : OSErr;
  13099.  
  13100.     __________________________________________________________________
  13101.  
  13102.     Assembly-language note:  SetTagBuffer is equivalent to a Control
  13103.     call with csCode = 8.
  13104.     __________________________________________________________________
  13105.  
  13106.     An application can change the information used in the file tags
  13107. buffer by calling SetTagBuffer. The buffPtr parameter points to a
  13108. buffer that contains the information to be used. If buffPtr is NIL, the
  13109. information in the file tags buffer isn't changed.
  13110.  
  13111.     If buffPtr isn't NIL, every time the Disk Driver reads a sector from
  13112. the disk, it stores the file tags in the file tags buffer
  13113. by calling SetTagBuffer. The buffPtr parameter points to a buffer that
  13114. contains the information to be used. If buffPtr is NIL, the
  13115. information in the file tags buffer isn't changed.
  13116.  
  13117.     The contents of the buffer pointed to by buffPtr are overwritten at
  13118. the end of every read request (which can be composed of a number of
  13119. sectors) instead of at the end of every sector. Each read request
  13120. places 12 bytes in the buffer for each sector, always beginning at the
  13121. start of the buffer. This way an application can examine the file tags
  13122. for a number of sequentially read sectors. If a read request is
  13123. composed of a number of sectors, the Disk Driver reads 12 bytes from
  13124. the buffer for each sector. For example, for a read request of five
  13125. sectors, the Disk Driver will read 60 bytes from the buffer.
  13126.  
  13127.     __________________________________________________________________
  13128.  
  13129.     Assembly-language note:  An assembly-language program can change
  13130.     the information used in the file tags buffer by storing a
  13131.     pointer to the buffer containing the information in the global
  13132.     variable TagBufPtr. If TagBufPtr is 0, the information in the
  13133.     file tags buffer isn't changed.
  13134.     __________________________________________________________________
  13135.  
  13136.     Result codes
  13137.  
  13138.             noErr       No error
  13139. \ DriveStatus
  13140. 20
  13141. FUNCTION DriveStatus (drvNum: INTEGER; VAR status: DrvSts) : OSErr;
  13142.  
  13143.     _________________________________________________________________
  13144.  
  13145.     Assembly-language note:  DriveStatus is equivalent to a Status
  13146.     call with csCode equivalent to teh globval constant drvStsCode.
  13147.     _________________________________________________________________
  13148.  
  13149.     DriveStatus returns information about the internal drive if drvNum
  13150. is 1, or about the external drive if drvNum is 2. The information is
  13151. returned in a record of type DrvSts:
  13152.  
  13153. TYPE DrvSts = RECORD
  13154.         track:      INTEGER;     {current track}
  13155.         writeProt:  SignedByte;  {bit 7=1 if volume is locked}
  13156.         diskInPlace:    SignedByte;  {disk in place}
  13157.         installed:  SignedByte;  {drive installed}
  13158.         sides:      SignedByte;  {bit 7=0 if single-sided drive}
  13159.         qLink:      QElmPtr;     {next queue entry}
  13160.         qType:      INTEGER;     {not used}
  13161.         dqDrive:    INTEGER;     {drive number}
  13162.         dqRefNum:   INTEGER;     {driver reference number}
  13163.         dqFSID:     INTEGER;     {file-system identifier}
  13164.         twoSideFmt: SignedByte;  {-1 if two-sided disk}
  13165.         needsFlush: SignedByte;  {reserved}
  13166.         diskErr:    INTEGER;     {error count}
  13167.       END;
  13168.  
  13169.     The diskInPlace field is 0 if there's no disk in the drive, 1 or 2
  13170. if there is a disk in the drive, or -4 to -1 if the disk was ejected in
  13171. the last 1.5 seconds. The installed field is 1 if the drive might be
  13172. connected to the Macintosh, and -1 if the drive isn't installed. 
  13173. The value oftwoSideFmt is valid only when diskInPlace = 2. The value
  13174. of diskErrs is incremented every time an error occurs internally within
  13175. the Disk Driver.
  13176.  
  13177.     Result codes
  13178.  
  13179.             noErr       No error
  13180.             nsDrvErr    No such drive
  13181. \ StartSound
  13182. 21
  13183. PROCEDURE StartSound (synthRec: Ptr; numBytes: LONGINT; completionRtn:
  13184.         ProcPtr);
  13185.  
  13186.     StartSound begins producing the sound(s) described by the
  13187. synthesizer buffer pointed to by synthRec. NumBytes indicates the
  13188. length of the synthesizer buffer (in bytes), and completionRtn points to
  13189. a completion routine to be executed when the sound finishes:
  13190.  
  13191.     - If completionRtn is POINTER(-1), the sound will be produced
  13192.       synchronously.
  13193.  
  13194.     - If completionRtn is NIL, the sound will be produced
  13195.       asynchronously, but no completion routine will be executed.
  13196.  
  13197.     - Otherwise, the sound will be produced asynchronously and the
  13198.       routine pointed to by completionRtn will be executed when the
  13199.       sound finishes.
  13200.  
  13201. (warning)
  13202.     You may want the completion routine to start the next
  13203.     sound when one sound finishes, but beware:  Completion
  13204.     routines are executed at the interrupt level, and
  13205.     shouldn't make any calls to the Memory Manager. Be sure
  13206.     to preallocate all the space you'll need. Or, instead of
  13207.     using a completion routine to start the next sound, the
  13208.     completion routine can post an application-defined event
  13209.     and your application's main event lop can start the next
  13210.     sound when it gets the event.
  13211.  
  13212.     Because the type of pointer for each type of synthesizer buffer is
  13213. different and the type of the synthRec parameter is Ptr, you'll need to
  13214. do something like the following example (which applies to the free-form
  13215. synthesizer):
  13216.  
  13217.     VAR myPtr: Ptr;
  13218.         myHandle: Handle;
  13219.         myFFPtr: FFSynthPtr;
  13220.         ...
  13221.     myHandle := NewHandle(buffSize);     {allocate space for the buffer}
  13222.     HLock(myHandle);             {lock the buffer}
  13223.     myPtr := myHandle^;          {dereference the handle}
  13224.     myFFPtr := FFSynthPtr(myPtr);        {coerce type to FFSynthPtr}
  13225.     myFFPtr^.mode := ffMode;         {identify the synthesizer}
  13226.     ...                  {fill the buffer with values}
  13227.                          {describing the sound}
  13228.     StartSound(myPtr,buffSize,POINTER(-1));    {produce the sound}
  13229.     HUnlock(myHandle)              {unlock the buffer}
  13230.  
  13231. where buffSize is the length of the synthesizer record.
  13232.  
  13233. The sounds are generated as follows:
  13234.  
  13235.     - Free-form synthesizer:  The magnitudes described by each byte in
  13236.       the waveform description are genereated sequentially until the
  13237.       number of bytes specified by the numBytes paramaeter have been
  13238.       written.
  13239.  
  13240.     - Square-wave synthesizer:  The sounds described by each sound
  13241.       triplet are generaed sequentially until either the end of the
  13242.       buffer has been reached (indicated by a count, amplitude, and
  13243.       duration of 0 in the square-wave buffer), or the number of bytes
  13244.       specified by the numBytes parameter have been written.
  13245.  
  13246.     - Four-tone synthesizer:  All four sounds are generated for the
  13247.       length of time specified by the duration integer in the four-tone
  13248.       record.
  13249. \ StopSound
  13250. 21
  13251. PROCEDURE StopSound;
  13252.  
  13253.     StopSound immediately stops the current StartSound call (if any),
  13254. executes the current StartSound call's completion routine (if any), and
  13255. cancels any pending asynchrounous StartSound calls.
  13256. \ SoundDone
  13257. 21
  13258. FUNCTION SoundDone : BOOLEAN;
  13259.  
  13260.     SoundDone returns TRUE if the Sound Driver isn't currently producing
  13261. sound and there are no asynchronous StartSound calls pending; otherwise
  13262. it returns FALSE.
  13263. \ GetSoundVol
  13264. 21
  13265. PROCEDURE GetSoundVol (VAR level: INTEGER);
  13266.  
  13267.     GetSoundVol returns the current speaker volume, from 0 (silence) to
  13268. 7 (loudest).
  13269.  
  13270.     __________________________________________________________________
  13271.  
  13272.     Assembly-language note:  To set the speaker volume level from
  13273.     assembly language, call this Pascal routine from your program.
  13274.     As a side effect, it will set the low-order three bits of the
  13275.     global variable SdVolume to the specified level.
  13276.     __________________________________________________________________
  13277.  
  13278. (note)
  13279.     Your program shouldn't change the speaker volume unless
  13280.     it's a Control Panel-like desk accessory, since it's
  13281.     really up to the user to choose the desired volume level
  13282.     via the Control Panel.
  13283. \ RAMSDOpen
  13284. 22
  13285. FUNCTION RAMSDOpen (whichPort: SPortSel; rsrcType: OSType; rsrcID:
  13286.         INTEGER) : OSErr;
  13287.  
  13288.     RAMSDOpen closes the ROM Serial Driver and opens the RAM input and
  13289. output drivers for the port identified by the whichPort parameter,
  13290. which must be a member of the SPortSel set:
  13291.  
  13292.     TYPE SPortSel = (sPortA, {modem port}
  13293.              sPortB  {printer port});
  13294.  
  13295.     RsrcType and rsrcID indicate the resource type and resource ID of
  13296. the RAM Serial Driver, which should be stored in your application's
  13297. resource file. (OSType is an Operating System Utility data type
  13298. declared the same as ResType in the Resource Manager.)
  13299.  
  13300.     Result codes
  13301.  
  13302.             noErr       No error
  13303.             openErr     Can't open driver
  13304. \ RAMSDClose
  13305. 22
  13306. PROCEDURE RAMSDClose (whichPort: SPortSel);
  13307.  
  13308.     RAMSDClose closes the RAM input and output drivers for the port
  13309. identified by the whichPort parameter, which must be a member of the
  13310. SPortSel set (defined int eh description of RAMSDOpen above).
  13311. \ SerReset
  13312. 22
  13313. FUNCTION SerReset (refNum: INTEGER; serConfig: INTEGER) : OSErr;
  13314.  
  13315.     SerReset resets and reinitializeds the input or output driver having
  13316. the reference number refNum according to the information in serConfig.
  13317. Figure 3 shows the format of serConfig.
  13318.  
  13319.     You can use the following predefined constants to set the values of
  13320. various bits of serConfig:
  13321.  
  13322. CONST   baud300     = 380;      {300 baud}
  13323.         baud600     = 189;      {600 baud}
  13324.         baud1200    = 94;       {1200 baud}
  13325.         baud1800    = 62;       {1800 baud}
  13326.         baud2400    = 46;       {2400 baud}
  13327.         baud3600    = 30;       {3600 baud}
  13328.         baud4800    = 22;       {4800 baud}
  13329.         baud7200    = 14;       {7200 baud}
  13330.         baud9600    = 10;       {9600 baud}
  13331.         baud19200   = 4;        {19200 baud}
  13332.         baud57600   = 0;        {57600 baud}
  13333.         stop10      = 16384;    {1 stop bit}
  13334.         stop15      = -32768;   {1.5 stop bits}
  13335.         stop20      = -16384;   {2 stop bits}
  13336.         noParity    = 8192;     {no parity}
  13337.         oddParity   = 4096;     {odd parity}
  13338.         evenParity  = 12288;    {even parity}
  13339.         data5       = 0;        {5 data bits}
  13340.         data6       = 2048;     {6 data bits}
  13341.         data7       = 1024;     {7 data bits}
  13342.         data8       = 3072;     {8 data bits}
  13343.  
  13344.  
  13345.     For example, the default setting of 9600 baud, eight data bits, two
  13346. stop bits, and no parity bit is equivalent to baud9600+data8+stop20+
  13347. noParity.
  13348. \ SerSetBuf
  13349. 22
  13350. FUNCTION SerSetBuf (refNum: INTEGER; serBPtr: Ptr; serBLen: INTEGER) :
  13351.         OSErr;
  13352.  
  13353.     SerSetBuf specifies a new input buffer for the input driver having
  13354. the reference number refNum. SerBPtr points to the buffer, and serBLen
  13355. specifies the number of bytes in the buffer. If serBLen is 0, a
  13356. 64-byte default buffer provided by the driver is used.
  13357.  
  13358. (warning)
  13359.     You must lock this buffer while it's in use.
  13360.  
  13361.     __________________________________________________________________
  13362.  
  13363.     Assembly-language note: SerSetBuf is equivalent to a Control
  13364.     call with csCode=9, csParam=serBPtr, and csParam+2=serBLen.
  13365.     __________________________________________________________________
  13366.  
  13367.     Result codes    noErr       No error
  13368. \ SerHShake
  13369. 22
  13370. FUNCTION SerHShake (refNum: INTEGER; flags: SerShk) : OSErr;
  13371.  
  13372.     SerHShake sets handshake options and other control information, as
  13373. specified by the flags parameter, for the input or output driver having
  13374. the reference number refNum. The flags parameter has the following
  13375. data structure:
  13376.  
  13377.     TYPE SerShk = PACKED RECORD
  13378.             fXOn: Byte; {XOn/XOff output flow control flag}
  13379.             fCTS: Byte;     {CTS hardware handshake flag}
  13380.             xOn:  CHAR; {XOn character}
  13381.             xOff: CHAR; {XOff character}
  13382.             errs: Byte; {errors that cause abort}
  13383.             evts: Byte; {status changes that cause events}
  13384.             fInX: Byte; {XOn/XOff input flow control flag}
  13385.             null: Byte  {not used}
  13386.                END;
  13387.  
  13388.     If fXOn is nonzero, XOn/XOff output flow control is enabled; if fInX
  13389. is nonzero, XOn/XOff input flow control is enabled. XOn and xOff specify
  13390. the XOn character and XOff character used for XOn/XOff flow control.
  13391. If fCTS is nonzero, CTS hardware handshake is enabled. The errs field
  13392. indicates which errors will cause input requests to be aborted; for
  13393. each type of error, there's  a predefined constant in which the 
  13394. corresponding bit is set:
  13395.  
  13396.     CONST parityErr     = 16;   {set for parity error}
  13397.           hwOverrunErr  = 32;   {set for hardware overrun error}
  13398.           framingErr    = 64;   {set for framing error}
  13399.  
  13400. (note)
  13401.     The ROM Serial Driver doesn't support XOn/XOff input flow
  13402.     control or aborts caused by error conditions.
  13403.  
  13404.     The evts field indicates whether changes in the CTS or break status
  13405. will cause the Serial Driver to post device driver events; you can use
  13406. the following predefined constants to set or test the value of evts:
  13407.  
  13408.     CONST ctsEvent   = 32;  {set if CTS change will cause event to}
  13409.                 {be posted}
  13410.           breakEvent = 128; {set if break status change will cause}
  13411.                     {event to be posted}
  13412.  
  13413.  
  13414. (warning)
  13415.     Use of this option is discouraged because of the long
  13416.     time that interrupts are disabled while such an event is
  13417.     posted.
  13418.  
  13419.     ___________________________________________________________________
  13420.  
  13421.     Assembly-language note:  SerHShake is equivalent to a Control
  13422.     call with csCode=10 and csParam through csParam+6 equivalent to
  13423.     the fields of a variable of type SerShk.
  13424.     ___________________________________________________________________
  13425.  
  13426.     Result codes    noErr       No error
  13427. \ SerSetBrk
  13428. 22
  13429. FUNCTION SerSetBrk (refNum: INTEGER) : OSErr;
  13430.  
  13431. SerSetBrk sets break mode in the input or output driver having the
  13432. reference number refNum.
  13433.  
  13434.     ___________________________________________________________________
  13435.  
  13436.     Assembly-language note:  SerSetBrk is equivalent to a Control
  13437.     call with csCode=12.
  13438.     ___________________________________________________________________
  13439.  
  13440.     Result codes
  13441.  
  13442.             noErr       No error
  13443. \ SerClrBrk
  13444. 22
  13445. FUNCTION SerClrBrk (refNumk: INTEGER) : OSErr;
  13446.  
  13447.     SerClrBrk clears break mode in the inplut or output driver having
  13448. the reference number refNum.
  13449.  
  13450.     __________________________________________________________________
  13451.  
  13452.     Assembly-language note:  SerClrBrk is equivalent to a Control
  13453.     call with csCode=11.
  13454.     __________________________________________________________________
  13455.  
  13456.     Result codes
  13457.  
  13458.         noErr       No error
  13459. \ SerGetBuf
  13460. 22
  13461. FUNCTION SerGetBuf (refNum: INTEGER; VAR count: LONGILNT) ; OSErr;
  13462.  
  13463.     SerGetBuf returns, in the count parameter, the number of bytes in
  13464. the buffer of the input driver having the reference number refNum.
  13465.  
  13466.     ____________________________________________________________________
  13467.  
  13468.     Assembly-language note:  SerGetBuf is equivalent to a Status
  13469.     call with csCode=2. The number of bytes in the buffer is
  13470.     returned in csParam.
  13471.     ____________________________________________________________________
  13472.  
  13473.     Result codes
  13474.  
  13475.         noErr       No error
  13476. \ SerErrFlag
  13477. 22
  13478. FUNCTION SerErrFlag (refNum: INTEGER; VAR serSta: SerStaRec) : OSErr;
  13479.  
  13480.     SerErrFlag returns in serSta three words of status information for
  13481. the input or output driver having the reference number refNum. The
  13482. serSta parameter has the following data structure:
  13483.  
  13484.     TYPE SerStaRec = PACKED RECORD
  13485.                cumErrs:   Byte; {cumulative errors}
  13486.                xOffSent:  Byte; {XOff sent as input flow}
  13487.                         { control}
  13488.                rdPend:    Byte; {read pending flag}
  13489.                wrPend:    Byte;     {write pending flag}
  13490.                ctsHold:   Byte; {CTS flow control hold flag}
  13491.                xOffHold:  Byte; {XOff received as output}
  13492.                             { flow control}
  13493.              END;
  13494.  
  13495.     CumErrs indicates which errors have occurred since the last time
  13496. SerErrFlag was called:
  13497.  
  13498.        CONST swOverrunErr = 1;  {set for software overrun error}
  13499.          parityErr    = 16; {set for parity error}
  13500.          hwOverrunErr = 32; {set for hardware overrun error}
  13501.          framingErr   = 64; {set for framing error}
  13502.  
  13503.  
  13504.     If the driver has sent an XOff character, xOffSent will be equal to
  13505. the following predefined constant:
  13506.  
  13507.     CONST xOffWasSent = $80;    {XOff character was sent}
  13508.  
  13509.     If the driver has a Read or Write call pending, rdPend or wrPend,
  13510. respectively, will be nonzero. If output has been suspended because
  13511. the hardware handshake was negated, ctsHold will be nonzero. If output
  13512. has been suspended because an XOff character was received, xOffHold
  13513. will be nonzero.
  13514.  
  13515.     __________________________________________________________________
  13516.  
  13517.     Assembly-language note:  SerStatus is equivalent to a Status
  13518.     call with csCode=8. The status information is returned in
  13519.     csParam through csParam+5.
  13520.     __________________________________________________________________
  13521.  
  13522.     Result codes    noErr       No error
  13523. \ MPPOpen
  13524. 23
  13525. FUNCTION MPPOpen : OSErr;  [Not in ROM]
  13526.  
  13527. MPPOpen first checks whether the .MPP driver is already loaded; if it
  13528. is, MPPOpen does nothing and returns noErr. If MPP hasn't been loaded,
  13529. MPPOpen attempts to load it into the system heap. If it succeeds, it
  13530. then initializes the driver's variables and goes through the process of
  13531. dynamically assigning a node ID to that Macintosh. On a Macintosh 512K
  13532. or XL, it also loads the .ATP driver and NBP code into the system heap.
  13533.  
  13534. If serial port B isn't configured for AppleTalk, or is already in use,
  13535. the .MPP driver isn't loaded and an appropriate result code is
  13536. returned.
  13537.  
  13538.     Result codes    noErr       No error
  13539.             portInUse   Port B is already in use
  13540.             portNotCf   Port B not configured for AppleTalk
  13541.  
  13542.  
  13543.  
  13544.  
  13545. \ MPPClose
  13546. 23
  13547. FUNCTION MPPClose : OSErr;   [Not in ROM]
  13548.  
  13549. MPPClose removes the .MPP driver, and any data structures associated
  13550. with it, from memory. If the .ATP driver or NBP code were also
  13551. installed, they'll also be removed. MPPClose also returns the use of
  13552. port B to the Serial Driver.
  13553.  
  13554. (warning)
  13555.     Since other co-resident programs may be using AppleTalk,
  13556.     it's strongly recommended that you never use this call. 
  13557.     MPPClose will completely disabale AppleTalk; the only way
  13558.     to restore ApleTalk is to call MPPOpen again.
  13559.  
  13560.  
  13561.  
  13562.  
  13563. \ LAPOpenProtocol
  13564. 23
  13565. FUNCTION LAPOpenProtocol (theLAPType: ABBYte; protoPtr: Ptr) : OSErr;
  13566.         [Not in ROM]
  13567.  
  13568. LAPOpenProtocol adds the LAP protocol type specified by theLAPType to
  13569. the node's protocol table. If you provide a pointer to a protocol 
  13570. handler in protoPtr, ALAP will send each frame with a LAP protocol type
  13571. of theLAPType to that protocol handler.
  13572.  
  13573. If protoPtr is NIL, the default protocol handler will be used for
  13574. receiving frames with a LAP protocol type of theLAPType. In this case,
  13575. to receive a frame you must acall LAPRead to provide the default
  13576. protocol handler with a buffer for placing the data. If, however,
  13577. you've written your own protocol handler and protoPtr points to it,
  13578. your protocol handler will have the responsibility fro receiving the
  13579. frame and it's not necessary to call LAPRead.
  13580.  
  13581.     Result codes    noErr       No error
  13582.             lapProtErr  Error attaching protocol type
  13583.  
  13584.  
  13585.  
  13586.  
  13587. \ LAPWrite
  13588. 23
  13589. FUNCTION LAPWrite (abRecord: ABRecHandle; async: BOOLEAN) : OSErr;
  13590.         [Not in ROM]
  13591.  
  13592.     ABusRecord
  13593.     ----------
  13594.        <--    abOpcode          {always tLAPWrite}
  13595.        <--    abResult          {result code}
  13596.        -->    abUserReference       {for your use}
  13597.        -->    lapAddress.dstNodeID      {destination node ID}
  13598.        -->    lapAddress.lapProtType    {LAP protocol type}
  13599.        -->    lapReqCount           {length of frame data}
  13600.        -->    lapDataPtr            {pointer to frame data}
  13601.  
  13602. LAPWrite sends a frame to another node. LAPReqCount and lapDataPtr
  13603. specify the length and location of the data to send. The
  13604. lapAddress.lapProtType field indicates the node ID of the node to
  13605. which the frame should be sent.
  13606.  
  13607. (note)
  13608.     The first two bytes of an ALAP frame's data must contain
  13609.     the length in bytes of the data, including the length
  13610.     bytes themselves.
  13611.  
  13612.     Result codes    noErr       No error
  13613.             excessCollsns   Unable to contact destination
  13614.                     node; packet not sent
  13615.  
  13616.  
  13617.  
  13618.  
  13619. \ LAPRead
  13620. 23
  13621. FUNCTION LAPRead (abRecord: ABRecHandle; async: BOOLEAN) : OSErr;
  13622.         [Not in ROM]
  13623.  
  13624.     ABusRecord
  13625.     ----------
  13626.        <--    abOpcode      {always tLAPWrite}
  13627.        <--    abResult      {result code}
  13628.        -->    abUserReference   {for your use}
  13629.        <--    lapAddress.dstNodeID  {packet's destination node ID}
  13630.        <--    lapAddress.srcNodeID  {packet's source node ID}
  13631.        -->    lapAddress.lapProtType{LAP protocol type}
  13632.        -->    lapReqCount       {buffer size in bytes}
  13633.        <--    lapActCount       {number of frame data bytes actually }
  13634.                     {received}
  13635.        -->    lapDataPtr        {pointer to buffer}
  13636.  
  13637.  
  13638. LAPRead receives a frame from another node. LAPReqCount and lapDataPtr
  13639. specify the length and location of the buffer that will receive the
  13640. frame data. If the buffer isn't large enough to hold all of the
  13641. incoming frame data, the extra bytes wil be discarded and buf2SmallErr
  13642. will be returned. The number of bytes actually received is returned in
  13643. lapActCount. Only frames with LAP protocol type equal to
  13644. lapAddress.lapProtType will be received. The node number of the
  13645. frame's source and destination nodes are returned in
  13646. lapAddress.srcNodeID and lapAddress.dstNodeID respectively. You can
  13647. determine if the packet was broadcast to you by examining the value of
  13648. lapAddress.dstNodeID--if the packet was broadcast it's equal to 255,
  13649. otherwise it's equal to your node ID.
  13650.  
  13651. (note)
  13652.     You should issue LAPRead calls only for LAP protocol
  13653.     types that were opened (via LAPOpenProtocol) to use the
  13654.     default protocol handler.
  13655.  
  13656.     Result codes    noErr       No error
  13657.             buf2SmallErr    Frame too large for buffer
  13658.             readQErr    Invalid protocol type or
  13659.                     protocol type not found in table
  13660.  
  13661.  
  13662.  
  13663.  
  13664. \ LAPRdCancel
  13665. 23
  13666. FUNCTION LAPRdCancel (abRecord: ABRecHandle) : OSErr;  [Not in ROM]
  13667.  
  13668. Given the handle to the ABusRecord of a previously made LAPRead call,
  13669. LAPRdCancel dequeues the LAPRead call, provided that a packet
  13670. satisfying the LAPRead has not already arrived. LAPRdCancel returns
  13671. noErr if the LAPRead call is successfully removed fdrom the queue. If
  13672. LAPRdCancel returns recNotFnd, check the abResult field to verify that
  13673. the LAPRead has been completed and determine its outcome.
  13674.  
  13675.     Result codes    noErr       No error
  13676.             readQErr    Invalid protocol type or
  13677.                     protocol type not found in table
  13678.             recNotFnd   ABRecord n ot found in queue
  13679.  
  13680.  
  13681.  
  13682.  
  13683. \ DDPOpenSocket
  13684. 23
  13685. FUNCTION DDPOpenSocket (VAR theSocket: Byte; sktListener: Ptr) : OSErr;
  13686.         [Not in ROM]
  13687.  
  13688. DDPOpenSocket adds a socket and its socket listener to the socket
  13689. table. If theSocket is nonzero (it must be in the range of 64 to 127),
  13690. it specifies the socket's number. If theSocket is 0, DDPOpenSocket
  13691. dynamically assigns a socket number in the range 128 to 254, and
  13692. returns it in theSocket. SktListener contains a pointer to the socket
  13693. listener; if it'e NIL, the default listener will be used.
  13694.  
  13695. If you're using the default socket listener, you must then call DDPRead
  13696. to receive a datagram (in order to specify buffer space for the default
  13697. socket listener). If, however, you've written your own socket listener
  13698. and sktListener points to it, your listener will provide buffers for
  13699. receiving datagrams and you shouldn't use DDPRead calls.
  13700.  
  13701. DDPOpenSocket will return ddpSktErr if you pass the number of an
  13702. already opened socket, if you pass a socket number greater than 127, or
  13703. if the socket table is full.
  13704.  
  13705. (note)
  13706.     The range of static socket numbers 1 through 63 is
  13707.     reserved for use by AppleTalk. Socket numbers 64 through
  13708.     127 are available for unrestricted experimental use.
  13709.  
  13710.     Result codes    noErr       No error
  13711.             ddpSktErr   Socket error
  13712.  
  13713.  
  13714.  
  13715.  
  13716. \ DDPCloseSocket
  13717. 23
  13718. FUNCTION DDPCloseSocket (theSocket: Byte) : OSErr;   [Not in ROM]
  13719.  
  13720. DDPCloseSocket removes the entry of the specified socket from the
  13721. socket table and cancels all pending DDPRead calls that have been made
  13722. to close a socket that isn't open, DDPCloseSocket will return
  13723. ddpSktErr.
  13724.  
  13725.     Result codes    noErr       No error
  13726.             ddpSktErr   Socket error
  13727.  
  13728.  
  13729.  
  13730. \ DDPWrite
  13731. 23
  13732. FUNCTION DDPWrite (abRecord: ABRecfHandle; doChecksum: BOOLEAN; async:
  13733.         BOOLEAN) : OSErr;   [Not in ROM]
  13734.  
  13735.     ABusRecord
  13736.     ----------
  13737.        <--    abOpcode      {always tDDPWrite}
  13738.        <--    abResult      {result code}
  13739.        -->    abUserReference   {for your use}
  13740.        -->    ddpType       {DDP protocol type}
  13741.        -->    ddpSocket         {source socket number}
  13742.        -->    ddpAddress        {destination socket address}
  13743.        -->    ddpReqCount       {length of datagram data}
  13744.        -->    ddpDataPtr        {pointer to buffer}
  13745.  
  13746. DDPWrite sends a datagram to another socket. DDPReqCount and
  13747. ddpDataPtr specify the length and location of the data to send. The
  13748. ddpType field indicates the DDP protocol type of the frame, and
  13749. ddpAddress is the complete internet address of the socket to which the
  13750. datagram should be sent. DDPSocket specifies the socket from which the
  13751. datagram should be sent. Datagrams sent over the internet to a node on
  13752. an AppleTalk network different from the sending node's network have an
  13753. optional software checksum to detect errors that might occur inside the
  13754. intermediate bridges. If doChecksum is TRUE, DDPWrite will compute
  13755. this checksum; if it's FALSE, this software checksum feature is
  13756. ignored.
  13757.  
  13758. (note)
  13759.     The destination socket can't be in the same node as the
  13760.     program making the DDPWrite call.
  13761.  
  13762.     Result codes    noErr       No error
  13763.             ddpLenErr   Datagram length too big
  13764.             ddpSktErr   Source socket not open
  13765.  
  13766.  
  13767.  
  13768. \ DDPRead
  13769. 23
  13770. FUNCTION DPRead (abRecord: ABRecfHandle; retChecksum: BOOLEAN; async:
  13771.         BOOLEAN) : OSErr;   [Not in ROM]
  13772.  
  13773.     ABusRecord
  13774.     ----------
  13775.        <--    abOpcode      {always tDDPWrite}
  13776.        <--    abResult      {result code}
  13777.        -->    abUserReference   {for your use}
  13778.        <--    ddpType       {DDP protocol type}
  13779.        -->    ddpSocket         {listening socket number}
  13780.        <--    ddpAddress        {source socket address}
  13781.        -->    ddpReqCount       {buffer size in bytes}
  13782.        <--    ddpActCount       {number of bytes actually received}
  13783.        -->    ddpDataPtr        {pointer to buffer}
  13784.        <--    ddpNodeID     {original destination node ID}
  13785.  
  13786.  
  13787. DDPRead receives a datagram from another socket. The length and
  13788. location of the buffer that will receive the data are specified by
  13789. ddpReqCount and ddpDataPtr, respectively. If the buffer isn't large
  13790. enough to hold all of the incoming frame data, the extra bytes will be
  13791. discarded and buf2SmallErr will be returned. The numbr of bytes
  13792. actually received is returned in ddpActCount. DDPSocket specifies the
  13793. socket to receive the datagram (the "listening" socket). The node to
  13794. which the packet was sent is returned in ddpNodeID; if the packet was
  13795. broadcast ddpNodeID will contain 255. The address of the socket that
  13796. sent the packet is returned in ddpAddress. If retCksumErrs is FALSE,
  13797. DDPRead will discard any packets received with an invalid checksum and
  13798. inform the caller of the error. If retCksumErr is TRUE, DDPRead will
  13799. deliver all packets, regardless of whether the checksum is valid or
  13800. not; it will also notify the caller when there's a checksum error.
  13801.  
  13802. (note)
  13803.     The sender of the datagram must be in a different node
  13804.     from the receiver. Youk should issue DDPRead calls only
  13805.     for receiving datagrams for sockets opened with the
  13806.     default socket listener; see the description of
  13807.     DDPOpenSocket.
  13808.  
  13809. (note)
  13810.     If DDPRead returns buf2SmallErr, it will deliver packets
  13811.     even if retCksukmErrs is FALSE.
  13812.  
  13813.     Result codes    noErr       No error
  13814.             buf2SmallErr    Datagram too large for buffer
  13815.             cksumErr    Checksum error
  13816.             ddpLenErr   Datagram length too big
  13817.             ddpSktErr   Socket error
  13818.             readQErr    Invalid socket or
  13819.                     socket not found in table
  13820.  
  13821.  
  13822.  
  13823. \ DDPRdCancel
  13824. 23
  13825. FUNCTION DDPRdCancel (abRecord: ABRecHandle) : OSErr;   [Not in ROM]
  13826.  
  13827. Given the handle to the ABusRecord of a previously made DDPRead call,
  13828. DDPRdCancel dequeues the DDPRead call, provided that a packet
  13829. satisfying the DDPRead hasn't already arrived. DDPRdCancel returns
  13830. noErr if the DDPRead call is successfully removed from the queue. If
  13831. DDPRdCancel returns recNotFnd, check the abResult field of abRecord to
  13832. verify that the DDPRead has been completed and determine its outcome.
  13833.  
  13834.  
  13835.     Result codes    noErr       No error
  13836.             readQErr    Invalid socket or
  13837.                     socket not found in table
  13838.             recNotFnd   ABRecord not found in queue
  13839.  
  13840.  
  13841.  
  13842. \ ATPLoad
  13843. 23
  13844. FUNCTION ATPLoad : OSErr;   [Not in ROM]
  13845.  
  13846. ATPLoad first verifies that the .MPP driver is loaded and running. If
  13847. it isn't, ATPLoad verifies that port B is configured for AppleTalk, and
  13848. is not in use, and then loads MPP into the system heap.
  13849.  
  13850. ATPLoad then loads the .ATP driver, unless it's already in memory. On
  13851. a Macintosh 128K, ATPLoad reads the .ATP driver from the system
  13852. resource file into the application heap; on a Macintosh 512K or XL, ATP
  13853. is read into the system heap.
  13854.  
  13855. (note)
  13856.     On a Macintosh 512K or XL, ATPLoad and MPPOpen perform
  13857.     essentially the same function.
  13858.  
  13859.  
  13860.  
  13861.     Result codes    noErr       No error
  13862.             portInUse   Port B is already in use
  13863.             portNotCf   Port B not configured for AppleTalk
  13864.  
  13865.  
  13866.  
  13867.  
  13868.  
  13869. \ ATPUnload
  13870. 23
  13871. FUNCTION ATPUnload : OSErr;   [Not in ROM]
  13872.  
  13873. ATPUnload makes the .ATP driver purgeable; the space isn't actually
  13874. released by the Memory Manager until necessary.
  13875.  
  13876. (note)
  13877.     This call applies only to a Macintosh 128K; on a
  13878.     Macintosh 512K or Macintosh XL, ATPUnload has no effect.
  13879.  
  13880.     Result codes    noErr       No error
  13881.  
  13882.  
  13883.  
  13884. \ ATPOpenSocket
  13885. 23
  13886. FUNCTION ATPOpenSocket (addrRcvd: AddrBlock; VAR atpSocket: Byte) :
  13887.         OSErr;   [Not in ROM]
  13888.  
  13889. ATPOpenSocket opens a socket for the purpose of receiving requests.
  13890. ATPSocket contains the socket number of the socket to open; if it's 0,
  13891. a number is dynamically assigned and returned in atpSocket. AddrRcvd
  13892. contains a filter of the sockets from which requests will be accepted.
  13893. A 0 in the network number, node ID, or socket number field of the
  13894. addrRcvd record acts as a "wild card"; for instance, a 0 in the socket
  13895. number field means that requests will be accepted from all sockets in
  13896. the node(s) specified by the network and node fields.
  13897.  
  13898.     Result codes    noErr       No error
  13899.             tooManySkts Socket table ful
  13900.             noDataArea  Too many outstanding ATP calls
  13901.  
  13902. (note)
  13903.     If you're only going to send requests and receive
  13904.     responses to these requests, you don't need to open an
  13905.     ATP socket. When you make the ATPSndRequest or
  13906.     ATPRequest call, ATP automatically opens a dynamically
  13907.     assigned socket for that purpose.
  13908.  
  13909.  
  13910.  
  13911. \ ATPCloseSocket
  13912. 23
  13913. FUNCTION ATPCLoseSocket (atpSocket: Byte) : OSErr;   [Not in ROM]
  13914.  
  13915. ATPCloseSocket closes the responding socket whose number is specified
  13916. by atpSocket. It releases the data structures associated with all
  13917. pending, asynchronous calls involving that socket; these pending calls
  13918. are completed immediately and return the result code sktClosed.
  13919.  
  13920.     Result codes    noErr       No error
  13921.             noDataArea  Too many outstanding ATP calls
  13922.  
  13923.  
  13924.  
  13925. \ ATPSndRequest
  13926. 23
  13927. FUNCTION ATPSndRequest (abRecord: ABRecHandle; async: BOOLEAN) : OSErr;
  13928.         [Not in ROM]
  13929.  
  13930.     ABusRecord
  13931.     ----------
  13932.        <--  abOpcode    {always tATPSndRequest}
  13933.        <--  abResult    {result code}
  13934.        -->  abUserReference {for your use}
  13935.        -->  atpAddress  {destination socket address}
  13936.        -->  atpReqCount {request size in bytes}
  13937.        -->  atpDataPtr  {pointer to buffer}
  13938.        -->  atpRspBDSPtr    {pointer to response BDS}
  13939.        -->  atpUserData {user bytes}
  13940.        -->  atpXO       {exactly-once flag}
  13941.        <--  atpEOM      {end-of-message flag}
  13942.        -->  atpTimeOut  {retry timeout interval in seconds}
  13943.        -->  atpRetries  {maximum number of retries}
  13944.        -->  atpNumBufs  {number of elements in response BDS}
  13945.        <--  atpNumRsp   {number of response packets actually }
  13946.                 {received}
  13947.  
  13948. ATPSndRequest sends a request to another socket. ATPAddress is the
  13949. internet address of the socket to which the request should be sent.
  13950. ATPDataPtr and atpReqCount specify the location and size of a buffer
  13951. that contains the request information to be sent. ATPUserData contains
  13952. the user bytes for the ATP header.
  13953.  
  13954. ATPSndRequest requires you to allocate a response BDS. ATPRspBDSPtr is
  13955. a pointer to the response BDS; atpNumBufs indicates the number of BDS
  13956. elements in the BDS (this is also the maximum number of response
  13957. datagrams that will be accepted). The number of response datagrams
  13958. actually received is returned in atpNumRsp; if a nonzero value is
  13959. returned, you can examine the response BDS to determine which packet
  13960. of the transaction were actually received. If the number returned is
  13961. less than requested, one of the folowing is true:
  13962.  
  13963.     - Some of the packets have been lost and the retry count has been
  13964.       exceeded.
  13965.  
  13966.     - ATPEOM is TRUE; this means that the response consisted of fewer
  13967.       packets than were expected, but that all packets sent were
  13968.       received (the last packet came with the atpEOM flag set).
  13969.  
  13970. ATPTimeOut indicates the length of time that ATPSndRequest should wait
  13971. for a response before retransmitting the request. ATPRetries indicates
  13972. the maximum number of retries ATPSndRequest shoud attempt. ATPXO
  13973. should be TRUE if you want the request to be part of an exactly-once
  13974. transaction.
  13975.  
  13976. ATPSndRequest completes when either the transaction is completed or the
  13977. retry count is exceeded.
  13978.  
  13979.     Result codes    noErr       No error
  13980.             reqFailed   Retry count exceeded
  13981.             tooManyReqs Too many concurrent requests
  13982.             noDataArea  Too many outstanding ATP calls
  13983.  
  13984.  
  13985.  
  13986. \ ATPRequest
  13987. 23
  13988. FUNCTION ATPRequest (abRecord: ABRecHandle; async: BOOLEAN) : OSErr;
  13989.         [Not in ROM]
  13990.  
  13991.     ABusRecord
  13992.     ----------
  13993.        <--  abOpcode    {always tATPRequest}
  13994.        <--  abResult    {result code}
  13995.        -->  abUserReference {for your use}
  13996.        -->  atpAddress  {destination socket address}
  13997.        -->  atpReqCount {request size in bytes}
  13998.        -->  atpDataPtr  {pointer to buffer}
  13999.        <--  atpActCount {number of bytes actually received}
  14000.        -->  atpUserData {user bytes}
  14001.        -->  atpXO       {exactly-once flag}
  14002.        <--  atpEOM      {end-of-message flag}
  14003.        -->  atpTimeOut  {retry timeout interval in seconds}
  14004.        -->  atpRetries  {maximum number of retries}
  14005.        <--  atpRspUData {user bytes received in transaction}
  14006.                 { response}
  14007.        -->  atpRspBuf   {pointer to response message buffer}
  14008.        -->  atpRspSize  {size of response message buffer}
  14009.  
  14010. ATPRequest is functionally analogous to ATPSndRequest. It sends a
  14011. request to another socket, but doesn't require the caller to set up and
  14012. use the BDS data structure to describe the response buffers.
  14013. ATPAddress indicates the socket to which the request should be sent.
  14014. ATPDataPtr and atpReqCount specify the location and size of a buffer
  14015. that contains the request information to be sent. ATPUserData contains
  14016. the uset bytes to be sent in the request's ATP header. ATPTimeOut
  14017. indicates the length of time that ATPRequest should wait for a response
  14018. before retransmitting the request. ATPRetries indicates the maximum
  14019. number of retries ATPRequest should attempt.
  14020.  
  14021. To use this call, you must have an area of contiguous buffer space
  14022. that's large enough to receive all expected datagrams. The various
  14023. datagrams will be assembled in this buffer and returned to you as a
  14024. complete message upon completion of the transaction. The address and
  14025. size of this buffer are pased in atpRspBuf and atpRspSize,
  14026. respectively. Upon completion of the call, the size ofthe received
  14027. response message is returned in atpActCount. The user bytes received
  14028. in the ATP header of the first response packet are returned in
  14029. atpRspUData. ATPXO should be TRUE if you want the request to be part
  14030. of an exactly-once transaction.
  14031.  
  14032. Although you don't provide a BDS, ATPRequest in fact creates one and
  14033. calls the .ATP driver (as in an ATPSndRequest call). For this reason,
  14034. the abRecord fields atpRspBDSPtr and atpNumBufs are used by ATPRequest;
  14035. you should not expect these fields to remain unaltered during or after
  14036. the function's execution.
  14037.  
  14038. For ATPRequest to receive and correctly deliver the response as a
  14039. single message, the responding end must, upon receiving the request
  14040. (with an ATPGetRequest call), generate the complete response as a
  14041. complete message in a single buffer and then call ATPResponse.
  14042.  
  14043. (note)
  14044.     The responding end could also use ATPSndRsp and ATPAddRsp
  14045.     provided that each response packet (except the last one)
  14046.     contains exactly 578 ATP data bytes; the last packet in
  14047.     the response can contain less than 578 ATP data bytes.
  14048.     Also, if this method is used, only the ATP user bytes of
  14049.     the first response packet will be delivered to the
  14050.     requester; any information in the user bytes of the
  14051.     remaining response packets will not be delivered.
  14052.  
  14053. ATPRequest completes when either the transaction is completed or the
  14054. retry count is exceeded.
  14055.  
  14056.     Result codes    noErr       No error
  14057.             reqFailed   Retry count exceeded
  14058.             tooManyReqs Too many concurrent requests
  14059.             sktClosed   Socket closed by a cancel call
  14060.             noDataArea  Too many outstanding ATP calls
  14061.  
  14062.  
  14063.  
  14064.  
  14065. \ ATPReqCancel
  14066. 23
  14067. FUNCTION ATPReqCancel (abRecord: ABRecHandle; async: BOOLEAN) : OSErr;
  14068.         [Not in ROM]
  14069.  
  14070. Given the handle to the ABusRecord of a previously made ATPSndRequest
  14071. or ATPRequest call, ATPReqCancel dequeues the ATPSndRequest or
  14072. ATPRequest call, provided that the call hasn't already completed.
  14073. ATPReqCancel returns noErr if the ATPSndRequest or ATPRequest call is
  14074. successfully removed from the queue. If it returns cbNotFound, check
  14075. the abResult field of abRecord to verify that the ATPSndRequest or
  14076. ATPRequest call has been completed and determine its outcome.
  14077.  
  14078.     Result codes    noErr       No error
  14079.             cbNotFound  ATP control block not found
  14080.  
  14081.  
  14082.  
  14083.  
  14084. \ ATPGetRequest
  14085. 23
  14086. FUNCTION ATPGetRequest (abRecord: ABRecHandle; async: BOOLEAN) :
  14087.         OSErr;   [Not in ROM]
  14088.  
  14089.     ABusRecord
  14090.     ----------
  14091.        <--  abOpcode    {always tATPGetRequest}
  14092.        <--  abResult    {result code}
  14093.        -->  abUserReference {for your use}
  14094.        -->  atpSocket   {listening socket number}
  14095.        <--  atpAddress  {source socket address}
  14096.        -->  atpReqCount {buffer size in bytes}
  14097.        -->  atpDataPtr  {pointer to buffer}
  14098.        <--  atpBitMap   {transaction bit map}
  14099.        <--  atpTransID  {transaction ID}
  14100.        <--  atpActCount {number of bytes actually received}
  14101.        <--  atpUserData {user bytes}
  14102.        <--  atpXO       {exactly-once flag}
  14103.  
  14104. ATPGetRequest sets up the mechanism to receive a request sent by either
  14105. an ATPSndRequest or an ATPRequest call. ATPSocket contains the socket
  14106. number of the socket that should listen for a request; this socket must
  14107. already have been opened by calling ATPOpenSocket. The address of the
  14108. socket from which the request was sent is returned in atpAddress.
  14109. ATPDataPtr specifies a buffer to store the incoming request;
  14110. atpReqCount indicates the size of the buffer in bytes. The number of
  14111. bytes actually received in the request is returned in atpActCount.
  14112. ATPUserData contains the user bytes from the ATP header. The
  14113. transaction bit map is returned in atpBitMap. The transaction ID is
  14114. returned in atpTransID. ATPXO will be TRUE if the request is part of
  14115. an exactly-once transaction.
  14116.  
  14117. ATPGetRequest completes when a request is received. To cancel an
  14118. asynchronous ATPGetRequest call, you must call ATPCloseSocket, but this
  14119. cancels all pending calls involving that socket.
  14120.  
  14121.  
  14122.     Result codes    noErr       No error
  14123.             badATPSkt   Bad responding socket
  14124.                 sktClosed   Socket closed by a cancel call
  14125.  
  14126.  
  14127.  
  14128.  
  14129. \ ATPSndRsp
  14130. 23
  14131. FUNCTION ATPSndRsp (abRecord: ABRecHandle; async: BOOLEAN) :
  14132.         OSErr;   [Not in ROM]
  14133.  
  14134.  
  14135.     ABusRecord
  14136.     ----------
  14137.        <--  abOpcode    {always tATPSndRsp}
  14138.        <--  abResult    {result code}
  14139.        -->  abUserReference {for your use}
  14140.        -->  atpSocket   {responding socket number}
  14141.        -->  atpAddress  {destination socket address}
  14142.        -->  atpRspBDSPtr    {pointer to response BDS}
  14143.        -->  atpTransID  {transaction ID}
  14144.        -->  atpEOM      {end-of-message flag}
  14145.        -->  atpNumBufs  {number of response packets being }
  14146.                 {sent}
  14147.        -->  atpBDSSize  {number of elements in response BDS}
  14148.  
  14149.  
  14150. ATPSndRsp sends a response to another socket. ATPSocket contains the
  14151. socket number from which the response should be sent and atpAddress
  14152. contains the internet address of the socket to which the response
  14153. should be sent. ATPTransID must contain the transaction ID. ATPEOM is
  14154. TRUE if the response BDS contains the final packet in a transaction
  14155. composed of a group of packets and the number of packets in the
  14156. response is less than expected. ATPRspBDSPtr points to the buffer data
  14157. structure containing the responses to be sent. ATPBDSSize indicates
  14158. the number of elements in the response BDS, and must be in the range 1
  14159. to 8. ATPNumBufs indicates the number of response packets being sent
  14160. with this call, and must be in the range 0 to 8.
  14161.  
  14162. (note)
  14163.     In some situations, you may want to send only part (or
  14164.     possibly none) of your response message back immediately.
  14165.     For instance, you might be requested to send back seven
  14166.     disk blocks, but have only enough internal memory to
  14167.     store one block. In this case, set atpBDSSize to 7
  14168.     (total number of response packets), atpNumBufs to 0
  14169.     (number of response packets currently being sent), and
  14170.     call ATPSndRsp. Then as you read in one block at a time,
  14171.     call ATPAddRsp until all seven response datagrams have
  14172.     been sent.
  14173.  
  14174. During exactly-once transactions, ATPSndRsp won't complete until the
  14175. release packet is received or the release timer expires.
  14176.  
  14177.  
  14178.     Result codes    noErr       No error
  14179.             badATPSkt   Bad responding socket
  14180.             noRelErr    No release received
  14181.                 sktClosed   Socket closed by a cancel call
  14182.             noDataArea  Too many outstanding ATP calls
  14183.  
  14184.  
  14185.  
  14186. \ ATPAddRsp
  14187. 23
  14188. FUNCTION ATPAddRsp (abRecord: ABRecHandle) : OSErr;   [Not in ROM]
  14189.  
  14190.  
  14191.     ABusRecord
  14192.     ----------
  14193.        <--  abOpcode    {always tATPAddRsp}
  14194.        <--  abResult    {result code}
  14195.        -->  abUserReference {for your use}
  14196.        -->  atpSocket   {responding socket number}
  14197.        -->  atpAddress  {destination socket address}
  14198.        -->  atpReqCount {buffer size in bytes}
  14199.        -->  atpDataPtr  {pointer to buffer}
  14200.        -->  atpTransID  {transaction ID}
  14201.        -->  atpUserData {user bytes}
  14202.        -->  atpEOM      {end-of-message flag}
  14203.        -->  atpNumRsp   {sequence number}
  14204.  
  14205. ATPAddRsp sends one additional response packet to a socket that has
  14206. already been sent the initial part of a response via ATPSndRsp.
  14207. ATPSocket contains the socket number from which the response should be
  14208. sent and atpAddress contains the internet address of the socket to
  14209. which the response should be sent. ATPTransID must contain the
  14210. transaction ID. ATPDataPtr and atpReqCount specify the location and
  14211. size of a buffer that contains the information to send; atpNumRsp is
  14212. the sequence number of the response. ATPEOM is TRUE if this repsonse
  14213. datagram is the final packet in a transaction composed of a group of
  14214. packets. ATPUserData contains the user bytes to be sent in this
  14215. response datagram's ATP header.
  14216.  
  14217. (note)
  14218.     No BDS is needed with ATPAddRsp because all pertinent
  14219.     information is passed within the record.
  14220.  
  14221.  
  14222.     Result codes    noErr       No error
  14223.             badATPSkt   Bad responding socket
  14224.             badBuffNum  Bad sequence number
  14225.             noSendResp  ATPAddRsp issued before ATPSndRsp
  14226.             noDataArea  Too many outstanding ATP calls
  14227.  
  14228.  
  14229.  
  14230.  
  14231. \ ATPResponse
  14232. 23
  14233. FUNCTION ATPResponse (abRecord: ABRecHandle; async: BOOLEAN) :
  14234.         OSErr;   [Not in ROM]
  14235.  
  14236.  
  14237.     ABusRecord
  14238.     ----------
  14239.        <--  abOpcode    {always tATPResponse}
  14240.        <--  abResult    {result code}
  14241.        -->  abUserReference {for your use}
  14242.        -->  aptSocket   {responding socket number}
  14243.        -->  atpAddress  {destination socket address}
  14244.        -->  atpRspUData {user bytes sent in transaction}
  14245.                 { response}
  14246.        -->  atpRspBuf   {pointer to response message buffer}
  14247.        -->  atpRspSize  {size of response message buffer}
  14248.  
  14249. ATPResponse is functionally analogous to ATPSndRsp. It sends a
  14250. response to a socket, but doesn't require the caller to provide a BDS.
  14251. ATPAddress must contain the complete network address of the socket to
  14252. which the response should be sent (the socket on which the corresponding
  14253. ATPGetRequest was issued). ATPRspBuf points to the buffer containing
  14254. the response message; the size of this buffer must be passed in
  14255. atpRspSize. The four user bytes to be sent in the ATP header of the
  14256. first response packet are passed in atpRspUData. The last packet of
  14257. the transaction response is sent with the EOM flag set.
  14258.  
  14259. Although you don't provide a BDS, ATPResponse in fact creates one and
  14260. calls the .ATP driver (as in an ATPSndRsp call). For this reason, the
  14261. abRecord fields atpRspBDSPtr and atpNumBufs are used by ATPResponse;
  14262. you should not expect these fields to remain unaltered during or after
  14263. the function's execution.
  14264.  
  14265. During exactly-once transactions ATPResponse won't complete until the
  14266. release packet is received or the release timer expires.
  14267.  
  14268. (warning)
  14269.     The maximum permissible size of the response message is
  14270.     4624 bytes.
  14271.  
  14272.  
  14273.     Result codes    noErr       No error
  14274.             badATPSkt   Bad responding socket
  14275.             noRelErr    No release received
  14276.             atpLenErr   Response too big
  14277.                 sktClosed   Socket closed by a cancel call
  14278.             noDataArea  Too many outstanding ATP calls
  14279.  
  14280.  
  14281.  
  14282.  
  14283. \ ATPRspCancel
  14284. 23
  14285. FUNCTION ATPRspCancel (abRecord: ABRecHandle; async: BOOLEAN) :
  14286.         OSErr;   [Not in ROM]
  14287.  
  14288. Given the handle to the ABusRecord of a previously made ATPSndRsp or
  14289. ATPResponse call, ATPRspCancel dequeues the ATPSndRsp or ATPResponse
  14290. call, provided that the call hasn't already completed. ATPRspCancel
  14291. returns noErr if the ATPSndRsp or ATPResponse call is successfully
  14292. removed from the queue. If it returns cbNotFound, check the abResult
  14293. field of abRecord to verify that the ATPSndRsp or ATPResponse call has
  14294. been completed and determine its outcome.
  14295.  
  14296.  
  14297.     Result codes    noErr       No error
  14298.             cbNotFound  ATP control block not found
  14299.             noDataArea  Too many outstanding ATP calls
  14300.  
  14301.  
  14302.  
  14303.  
  14304. \ NBPRegister
  14305. 23
  14306. FUNCTION NBPRegister (abRecord: ABRecHandle; async: BOOLEAN) :
  14307.         OSErr;   [Not in ROM]
  14308.  
  14309.  
  14310.     ABusRecord
  14311.     ----------
  14312.        <--  abOpcode        {always tNBPRegister}
  14313.        <--  abResult        {result code}
  14314.        -->  abUserReference     {for your use}
  14315.        -->  nbpEntityPtr        {pointer to entity name}
  14316.        -->  nbpBufPtr       {pointer to buffer}
  14317.        -->  nbpBufSize      {buffer size in bytes}
  14318.        -->  nbpAddress.aSocket  {socket address}
  14319.        -->  nbpRetransmitInfo   {retransmission information}
  14320.  
  14321. NBPRegister adds the name and address of an entity to the node's names
  14322. table. NBPEntityPtr points to a variable of type EntityName containing
  14323. the entity's name. If the name is already registered, NBPRegister
  14324. returns the result code nbpDuplicate. NBPBufPtr and nbpBufSize
  14325. specify the location and size of a buffer for NBP to use internally.
  14326. The buffer must contain at least 12 bytes plus the length of the entity
  14327. name.
  14328.  
  14329. (warning)
  14330.     This buffer must not be altered or released until the
  14331.     name is removed from the names table via an NBPRemove
  14332.     call. If you allocate the buffer through a NewHandle
  14333.     call, the handle must be locked as long as the name is
  14334.     registered.
  14335.  
  14336.     Result codes    noErr       No error
  14337.             nbpDuplicate    Duplicate name already exists
  14338.  
  14339.  
  14340.  
  14341.  
  14342. \ NBPLookup
  14343. 23
  14344. FUNCTION NBPLookup (abRecord: ABRecHandle; async: BOOLEAN) :
  14345.         OSErr;   [Not in ROM]
  14346.  
  14347.  
  14348.     ABusRecord
  14349.     ----------
  14350.        <--  abOpcode        {always tNBPLookup}
  14351.        <--  abResult        {result code}
  14352.        -->  abUserReference     {for your use}
  14353.        -->  nbpEntityPtr        {pointer to entity name}
  14354.        -->  nbpBufPtr       {pointer to buffer}
  14355.        -->  nbpBufSize      {buffer size in bytes}
  14356.        <->  nbpDataField        {number of addresses received}
  14357.        -->  nbpRetransmitInfo   {retransmission information}
  14358.  
  14359. NBPLookup returns the addresses of all entities with a specified name.
  14360. NBPEntityPtr points to a variable of type EntityName containing the
  14361. name of the entity whose address should be returned. (Meta-characters
  14362. are allowed in the entity name.)  NBPBufPtr and NBPBufSize contain the
  14363. location and size of an area of memory in which the entities' addresses
  14364. should be returned. NBPDataField indicates the maximum number of
  14365. matching names to find addresses for; the actual number of addresses
  14366. found is returned in NBPDataField. NBPRetransmitInfo contains the
  14367. retry interval and the retry count.
  14368.  
  14369.     Result codes    noErr       No error
  14370.             nbpBuffOvr  Buffer overflow
  14371.  
  14372.  
  14373.  
  14374. \ NBPExtract
  14375. 23
  14376. FUNCTION NBPExtract (theBuffer: Ptr; numInBuf: INTEGER; whichOne:
  14377.         INTEGER; VAR abEntityName; VAR address: AddrBlock)
  14378.         : OSErr;   [Not in ROM]
  14379.  
  14380. NBPExtract retruns one address from the list of addresses returned by
  14381. NBPLookup. TheBuffer and numInBuf indicate the location and number of
  14382. tuples in the buffer. WhichOne specifies which one of the tuples in
  14383. the buffer should be returned in the abEntity and adress parameters.
  14384.  
  14385.     Result codes    noErr       No error
  14386.             extractErr  Can't find tuple in buffer
  14387.  
  14388.  
  14389.  
  14390. \ NBPConfirm
  14391. 23
  14392. FUNCTION NBPConfirm (abRecord: ABRecHandle; async: BOOLEAN) :
  14393.         OSErr;   [Not in ROM]
  14394.  
  14395.     ABusRecord
  14396.     ----------
  14397.        <--  abOpcode        {always tNBPConfirm}
  14398.        <--  abResult        {result code}
  14399.        -->  abUserReference     {for your use}
  14400.        -->  nbpEntityPtr        {pointer to entity name}
  14401.        <--  nbpDataField        {number of addresses received}
  14402.        -->  nbpAddress      {socket address}
  14403.        -->  nbpRetransmitInfo   {retransmission information}
  14404.  
  14405. NBPConfirm confirms that an entity known by name and address still
  14406. exists (is still entered in the names directory). NBPEntityPtr points
  14407. to a variable of type EntityName that contains the name to confirm, and
  14408. nbpAddress specifies the address to be confirmed. (No meta-characters
  14409. are allowed in the entity name.)  NBPRetransmitInfo contains the retry
  14410. interval and the retry count. The correct socket number of the entity
  14411. is returned in nbpDataField. NBPConfirm is more efficient than
  14412. NBPLookup in terms of network traffic.
  14413.  
  14414.  
  14415.     Result codes    noErr       No error
  14416.             nbpConfDiff Name confirmed for different socket
  14417.             nbpNoConfirm    Name not confirmed
  14418.  
  14419.  
  14420.  
  14421. \ NBPRemove
  14422. 23
  14423. FUNCTION NBPRemove (abEntity: EntityPtr) : OSErr;   [Not in ROM]
  14424.  
  14425. NBPRemove removes an entity name from the names table of the caller's
  14426. node.
  14427.  
  14428.  
  14429.     Result codes    noErr       No error
  14430.             nbpNotFound Name not found
  14431.  
  14432.  
  14433.  
  14434. \ NBPLoad
  14435. 23
  14436. FUNCTION NBPLoad : OSErr;   [Not in ROM]
  14437.  
  14438. On a Macintosh 128K, NBPLoad reads the AppleTalk Manager's NBP code
  14439. from the system resource file into the application heap. On a
  14440. Macintosh 512K or XL, NBPLoad has no effect since the NBP code should
  14441. have already been loaded when the .MPP driver was opened. Normally
  14442. you'll never need to call NBPLoad because the AppleTalk Manager calls
  14443. it when necessary.
  14444.  
  14445.     Result codes    noErr       No error
  14446.  
  14447.  
  14448.  
  14449. \ NBPUnload
  14450. 23
  14451. FUNCTION NBPUnload : OSErr;   [Not in ROM]
  14452.  
  14453. NBPUnload makes the NBP code purgeable; the space isn't actually
  14454. released by the Memory Manager until necessary.
  14455.  
  14456. (note)
  14457.     This call applies only to a Macintosh 128K; on a
  14458.     Macintosh 521K or Macintosh XL, NBPUnload has no effect.
  14459.  
  14460.     Result codes    noErr       No error
  14461.  
  14462.  
  14463.  
  14464.  
  14465. \ GetNodeAddress
  14466. 23
  14467. FUNCTION GetNodeAddress (VAR myNode,myNet: INTEGER) : OSErr;[Not in ROM]
  14468.  
  14469. GetNodeAddress returns the current node ID and network number of the
  14470. caller. If the .MPP driver isn't installed, it returns noMPPErr. If
  14471. myNet contains 0, this means that a bridge hasn't yet been found.
  14472.  
  14473.     Result codes    noErr       No error
  14474.             noMPPErr    MP driver not installed
  14475.  
  14476.  
  14477.  
  14478. \ IsMPPOpen
  14479. 23
  14480. FUNCTION IsMPPOpen : BOOLEAN;   [Not in ROM]
  14481.  
  14482. IsMPPOpen returns TRUE if the .MPP driver is loaded and running.
  14483.  
  14484.  
  14485.  
  14486. \ IsATPOpen
  14487. 23
  14488. IsATPOpen : BOOLEAN;   [Not in ROM]
  14489.  
  14490. IsATPOpen returns TRUE if the .ATP driver is loaded and running.
  14491.  
  14492.  
  14493. \ VInstall
  14494. 24
  14495. FUNCTION VInstall (vblTaskPtr: QElemPtr) : OSErr;
  14496.  
  14497.     _________________________________________________________________
  14498.  
  14499.     Trap macro  _VInstall
  14500.  
  14501.     On entry    A0:  vblTaskPtr (pointer)
  14502.  
  14503.     On exit     D0:  result code (integer)
  14504.     _________________________________________________________________
  14505.  
  14506.     VInstall adds the task described by vblTaskPtr to the vertical
  14507. retrace queue. Your application must fill in all fields of the task
  14508. except qLink. VInstall returns one of the result codes listed below.
  14509.  
  14510.     Result codes
  14511.  
  14512.             noErr       No error
  14513.             vTypErr     QType field isn't ORD(vType)
  14514.  
  14515. \ VRemove
  14516. 24
  14517. FUNCTION VRemove (vblTaskPtr: QElemPtr) : OSErr;
  14518.  
  14519.     _________________________________________________________________
  14520.  
  14521.     Trap macro  _VRemove
  14522.  
  14523.     On entry    A0:  vblTaskPtr (pointer)
  14524.  
  14525.     On exit     D0:  result code (integer)
  14526.     _________________________________________________________________
  14527.  
  14528.  
  14529.     Result codes
  14530.  
  14531.             noErr       No error
  14532.             vTypErr     QType field isn't ORD(vType)
  14533.             qErr        Task entry isn't in the queue
  14534. \ GetVBLQHdr
  14535. 24
  14536. FUNCTION GetVBLQHdr : QHdrPtr;   [Pascal only]
  14537.  
  14538.     GetVBLQHdr returns a pointer to the vertical retrace queue.
  14539. \ HandToHand
  14540. 25
  14541. FUNCTION HandToHand (VAR theHndl: Handle) : OSErr;
  14542.  
  14543.     _________________________________________________________________
  14544.  
  14545.     Trap macro  _HandToHand
  14546.  
  14547.     On entry    A0:  theHndl (handle)
  14548.  
  14549.     On exit     A0:  theHndl (handle)
  14550.                 D0:  result code (word)
  14551.     __________________________________________________________________
  14552.  
  14553.     HandToHand copies the information to which theHndl is a handle and
  14554. returns a new handle to the copy in theHndl. Since HandToHand replaces
  14555. the input parameter with a new handle, you should retain the original
  14556. value of the input parameter somewhere else, or you won't be able to
  14557. access it. For example:
  14558.  
  14559.     VAR x,y: Handle;
  14560.         err: OSErr;
  14561.  
  14562.     y := x;
  14563.     err := HandToHand(y)
  14564.  
  14565.     The original handle remains in x while y becomes a different handle
  14566. to identical data.
  14567.  
  14568.     Result codes
  14569.  
  14570.             noErr       No error
  14571.             memFullErr  Not enough room in heap
  14572.             nilHandleErr    NIL master pointer
  14573.             memWZErr    Attempt to operate on a free block
  14574. \ PtrToHand
  14575. 25
  14576. FUNCTION PtrToHand (srcPtr: Ptr; VAR dstHndl: Handle; size: LONGINT) :
  14577.         OSErr;
  14578.  
  14579.     __________________________________________________________________
  14580.  
  14581.     Trap macro  _PtrToHand
  14582.  
  14583.     On entry    A0:  srcPtr (pointer)
  14584.                 D0:  size (long word)
  14585.  
  14586.     On exit     A0:  dstHndl (handle)
  14587.                 D0:  result code (word)
  14588.     ___________________________________________________________________
  14589.  
  14590.  
  14591.  
  14592.  
  14593.  
  14594.     PtrToHand returns in dstHndl a newly created handle to a copy of the
  14595. number of bytes specified by the size parameter, beginning at the
  14596. location specified by srcPtr.
  14597.  
  14598.     Result codes
  14599.  
  14600.             noErr       No error
  14601.             memFullErr  Not enough room in heap
  14602. \ PtrToXHand
  14603. 25
  14604. FUNCTION PtrToXHand (srcPtr: Ptr; VAR dstHndl: Handle; size: LONGINT) :
  14605.                     OSErr;
  14606.  
  14607.  
  14608.     __________________________________________________________________
  14609.  
  14610.     Trap macro  _PtrToXHand
  14611.  
  14612.     On entry    A0:  srcPtr (pointer)
  14613.                 A1:  dstHndl (handle)
  14614.                 D0:  size (long word)
  14615.  
  14616.     On exit     A1:  dstHndl (handle)
  14617.                 D0:  result code (word)
  14618.     ___________________________________________________________________
  14619.  
  14620.     PtrToXHand takes the existing handle specified by dstHndl and makes
  14621. it a handle to a copy of the number of bytes specified by the size
  14622. parameter, beginning at the location specified by srcPtr.
  14623.  
  14624.     Result codes
  14625.  
  14626.             noErr       No error
  14627.             memFullErr  Not enough room in heap
  14628.             nilHandleErr    NIL master pointer
  14629.             memWZErr    Attempt to operate on a free block
  14630. \ HandAndHand
  14631. 25
  14632. FUNCTION HandAndHand (aHndl,bHndl: Handle) : OSErr;
  14633.  
  14634.     __________________________________________________________________
  14635.  
  14636.     Trap macro  _PtrToXHand
  14637.  
  14638.     On entry    A0:  aHndl (handle)
  14639.                 A1:  bHndl (handle)
  14640.  
  14641.     On exit     A1:  bHndl (handle)
  14642.                 D0:  result code (word)
  14643.     ___________________________________________________________________
  14644.  
  14645.     HandAndHand concatenates the information to which aHndl is a handle
  14646. onto the end of the information to which bHndl is a handle.
  14647.  
  14648.  
  14649.     Result codes
  14650.  
  14651.             noErr       No error
  14652.             memFullErr  Not enough room in heap
  14653.             nilHandleErr    NIL master pointer
  14654.             memWZErr    Attempt to operate on a free block
  14655. \ PtrAndHand
  14656. 25
  14657. FUNCTION PtrAndHand (pntr: Ptr; hndlk: Handle; size: LONGINT) : OSErr;
  14658.  
  14659.     __________________________________________________________________
  14660.  
  14661.     Trap macro  _PtrToXHand
  14662.  
  14663.     On entry    A0:  pntr (pointer)
  14664.                 A1:  hndl (handle)
  14665.                 D0:  size (long word)
  14666.  
  14667.     On exit     A1:  hndl (handle)
  14668.                 D0:  result code (word)
  14669.     ___________________________________________________________________
  14670.  
  14671.     PtrAndHand takes the number of bytes specified by the size
  14672. parameter, beginning at the location specified by pntr, and concatenates
  14673. them onto the end of the information to which hndl is a handle.
  14674.  
  14675.     Result codes
  14676.  
  14677.             noErr       No error
  14678.             memFullErr  Not enough room in heap
  14679.             nilHandleErr    NIL master pointer
  14680.             memWZErr    Attempt to operate on a free block
  14681. \ NGetTrapAddress
  14682. 25
  14683. FUNCTION NGetTrapAddress (trapNum: INTEGER; tType: TrapType) : LongInt;
  14684.                             [Not in ROM]
  14685.  
  14686.     NGetTrapAddress is identical to GetTrapAddress except that it
  14687. requires you to specify in tType whether the given routine is an
  14688. Operating System or a Toolbox trap.
  14689.  
  14690. Trap macro  _GetTrapAddress ,NEWOS      (bit 9 set, bit 10 clear)
  14691.             _GetTrapAddress ,NEWTOOL    (bit 9 set, bit 10 set)
  14692.  
  14693. On entry    D0:  trapNum (word)
  14694.  
  14695. On exit     A0:  address of routine
  14696. \ NSetTrapAddress
  14697. 25
  14698. FUNCTION NSetTrapAddress (trapAddr: LongInt; trapNum: INTEGER;
  14699.                             tType: TrapType);  [Not in ROM]
  14700.  
  14701.     NSetTrapAddress is identical to SetTrapAddress except that it
  14702. requires you to specify in tType whether the given routine is an
  14703. Operating System or a Toolbox trap.
  14704.  
  14705. Trap macro  _SetTrapAddress ,NEWOS      (bit 9 set, bit 10 clear)
  14706.             _SetTrapAddress ,NEWTOOL    (bit 9 set, bit 10 set)
  14707.  
  14708. On entry    A0:  trapAddr (address)
  14709.             D0:  trapNum (word)
  14710. \ RelString
  14711. 25
  14712. FUNCTION RelString (aStr,bStr: Str255; caseSens,diacSens: BOOLEAN)
  14713.                     : INTEGER;
  14714.  
  14715.     RelString is similar to EqualString except that it indicates whether
  14716. the first string is less than, equal to, or greater than the second
  14717. string by returning either –1, 0, or 1 respectively.
  14718.  
  14719.  
  14720. Trap macro  _RelString
  14721.             _RelString ,MARKS       (sets bit 9, for diacSens=FALSE)
  14722.             _RelString ,CASE        (sets bit 10, for caseSens=TRUE)
  14723.             _RelString ,MARKS,CASE  (sets bits 9 and 10)
  14724.  
  14725. On entry    A0:  pointer to first character of first string
  14726.             A1:  pointer to first character of second string
  14727.             D0:  high-order word:  length of first string
  14728.                  low-order word:  length of second string
  14729.  
  14730. On exit D0:    –1 if first string less than second,
  14731.                 0 if equal,
  14732.                 1 if first string greater than second (long word)
  14733.  
  14734.  
  14735.     RelString follows the sort order described in chapter 19 of
  14736. Volume II except for the reordering of the following ligatures:
  14737.  
  14738. Æ falls between Å and a
  14739. æ falls between å and B
  14740. Œ falls between Ø and o
  14741. œ falls between ø and P
  14742. ß falls between s and T
  14743.  
  14744.     If diacSens is FALSE, diacritical marks are ignored; RelString
  14745. strips diacriticals according to the following table:
  14746.  
  14747. A   <—  Ä, Å, À, Ã
  14748. C   <—  Ç
  14749. E   <—  É
  14750. N   <—  Ñ
  14751. O   <—  Ö, Õ, Ø
  14752. U   <—  Ü
  14753. a   <—  á, à, â, ä, ã, å, ª
  14754. c   <—  ç
  14755. e   <—  é, è, ê, ë
  14756. i   <—  í, ì, î, ï
  14757. n   <—  ñ
  14758. o   <—  ó, ò, ô, ö, õ, ø, º
  14759. u   <—  ú, ù, û, ü
  14760. y   <—  ÿ
  14761.  
  14762. Note:   This stripping is identical to that performed by the UprString
  14763.         procedure when the diacSens parameter is FALSE.
  14764.  
  14765.     If caseSens is FALSE, the comparison is not case-sensitive;
  14766. RelString performs a conversion from lower-case to upper-case characters
  14767. according to the following table:
  14768.  
  14769. A   <—  a
  14770. . . .   <—  . . .
  14771. Z   <—  z
  14772. À   <—  à
  14773. à  <—  ã
  14774. Ä   <—  ä
  14775. Å   <—  å
  14776. Æ   <—  æ
  14777. Ç   <—  ç
  14778. É   <—  é
  14779. Ñ   <—  ñ
  14780. Ö   <—  ö
  14781. Õ   <—  õ
  14782. Ø   <—  ø
  14783. Œ   <—  œ
  14784. Ü   <—  ü
  14785.  
  14786. Note:   This conversion is identical to that performed by the UprString
  14787.         procedure.
  14788.  
  14789. \ Environs
  14790. 25
  14791. PROCEDURE Environs (VAR rom,machine: INTEGER)  [Not in ROM]
  14792.  
  14793.     In the rom parameter, Environs returns the current ROM version
  14794. number (for a Macintosh XL, the version number of the ROM image
  14795. installed by MacWorks). To use the 128K ROM  information described
  14796. in this volume, the version number should be greater than or equal
  14797. to 117 ($75). In the machine parameter, Environs returns an indication
  14798. of which machine is in use, as follows:
  14799.  
  14800.  
  14801. CONST   macXLMachine    = 0;    {Macintosh XL}
  14802.         macMachine      = 1;    {Macintosh 128K, 512K, 512K upgraded, }
  14803.                                 { 512K enhanced, or Macintosh Plus}
  14804.  
  14805. Note:  The machine parameter does not distinguish between the Macintosh
  14806. 128K, 512K, 512K upgraded, 512K enhanced, and Macintosh Plus.
  14807. ________________________________________________________________________
  14808.  
  14809. Assembly-language note:  From assembly language, you can get this
  14810. information from the word that’s at an offset of 8 from the beginning
  14811. of ROM (which is stored in the global variable ROMBase). The format of
  14812. this word is $00xx for the Macintosh 128K, 512K, 512K upgraded, 512K
  14813. enhanced, or Macintosh Plus, and $xxFF for the Macintosh XL, where xx
  14814. is the ROM version number. (The ROM version number will always be
  14815. between $01 and $FE.)
  14816. ________________________________________________________________________
  14817.  
  14818. \ EqualString
  14819. 25
  14820. FUNCTION EqualString (aStr,bStr: Str255; caseSens,diacSens: BOOLEAN) :
  14821.                         BOOLEAN;
  14822.  
  14823.     _________________________________________________________________
  14824.  
  14825.     Trap macro  _CmpString
  14826.                 _CmpString  ,MARKS          (sets bit 9, for
  14827.                                              diacSens=FALSE)
  14828.                 _CmpString  ,CASE           (sets bit 10, for
  14829.                                              caseSens=TRUE)
  14830.                 _CmpString   ,MARKS,CASE    (sets bits 9 and 10)
  14831.  
  14832.  
  14833.     On entry    A0:  pointer to first character of first string
  14834.                 A1:  pointer to first character of second string
  14835.                 D0:  high-order word: length of first string
  14836.                      low-order word:  length of second string
  14837.  
  14838.     On exit     D0:  0 if strings equal, 1 if strings not equal
  14839.                     (long word)
  14840.     ___________________________________________________________________
  14841.  
  14842.     EqualString compares the two given strings for equality on the basis
  14843. of their ASCII values. If caseSens is TRUE, uppercase characters are
  14844. distinguished from the corresponding lowercase characters. If diacSens
  14845. is FALSE, diacritical marks are ignored dring the comparison. The
  14846. function returns TRUE if the strings are equal.
  14847.  
  14848. (note)
  14849.     See also the International Utilities Package function
  14850.     IUEqualString, as described in the Macintosh Packages
  14851.     manual.
  14852. \ UprString
  14853. 25
  14854. PROCEDURE UprString (VAR theString: Str255; diacSens: BOOLEAN);
  14855.  
  14856.     _________________________________________________________________
  14857.  
  14858.     Trap macro  _UprString
  14859.                 _UprString  ,MARKS  (sets bit 9, for diacSens=FALSE)
  14860.  
  14861.     On entry    A0:  pointer to first charactaer of string
  14862.                 D0:  length of string (word)
  14863.  
  14864.     On exit     A0:  pointer to first character of string
  14865.     __________________________________________________________________
  14866.  
  14867.     UprString converts any lowercase letters in the given string to
  14868. uppercase, returning the converted string in theString. In addition,
  14869. diacritical marks are stripped from the string if diacSens is FALSE.
  14870. \ ReadDateTime
  14871. 25
  14872. FUNCTION ReadDateTime (VAR secs: LONGINT) : OSErr;
  14873.  
  14874.     __________________________________________________________________
  14875.  
  14876.     Trap macro  _ReadDateTime
  14877.  
  14878.     On entry    A0:  pointer to long word secs
  14879.  
  14880.     On exit     A0:  pointer to long word secs
  14881.                 D0:  result code (word)
  14882.     __________________________________________________________________
  14883.  
  14884.     ReadDateTime copies the date and time stored in the clock chip to a
  14885. low-memory location and returns it in the secs parameter. This routine
  14886. is called at system startup; you'll probably never need to call it
  14887. yourself. Instead you'll call GetDateTime (see below).
  14888.  
  14889.     __________________________________________________________________
  14890.  
  14891.     Assembly-language note:  The low-memory location to which
  14892.     ReadDateTime copies the date and time is the global variable
  14893.     Time.
  14894.     __________________________________________________________________
  14895.  
  14896.  
  14897.     Result codes    noErr       No error
  14898.                     clkRdErr    Unable to read clock
  14899. \ GetDateTime
  14900. 25
  14901. PROCEDURE GetDateTime (VAR secs: LONGINT);   [Not in ROM]
  14902.  
  14903.     GetDateTime returns in the secs parameter the contents of the low-
  14904. memory location in which the date and time is stored; if the date and
  14905. time is properly set, secs will contain the number of seconds between
  14906. midnight, January 1, 1904 and the time that the function was called.
  14907.  
  14908. (note)
  14909.     If your application disables interrupts for longer than a
  14910.     second, the number of seconds returned will not be exact.
  14911.  
  14912.  
  14913.  
  14914.     ________________________________________________________________
  14915.  
  14916.     Assembly-language note:  Assembly-language programmers can just
  14917.     access the global variable Time.
  14918.     ________________________________________________________________
  14919.  
  14920.     If you wish, you can convert the value returned by GetDateTime to a
  14921. date/time record by calling the Secs2Date procedure.
  14922.  
  14923. (note)
  14924.     Passing the value returned by GetDateTime to the
  14925.     International Utilities Package procedure IUDateString or
  14926.     IUTimeString will yield a string representing the
  14927.     corresponding date or time of day, respectively.
  14928. \ SetDateTime
  14929. 25
  14930. FUNCTION SetDateTime (secs: LONGINT) : OSErr;
  14931.  
  14932.     _________________________________________________________________
  14933.  
  14934.     Trap macro  _SetDateTime
  14935.  
  14936.     On entry    D0:  secs (long word)
  14937.  
  14938.     On exit     D0:  result code (word)
  14939.     _________________________________________________________________
  14940.  
  14941.     SetDateTime takes a number of seconds since midnight, January 1,1904
  14942. as specified by the secs parameter and writes it to the clock chip as
  14943. the current date and time. It then attempts to read the value just
  14944. written and verify it by comparing it to the secs parameter.
  14945.  
  14946.     _________________________________________________________________
  14947.  
  14948.     Assembly-language note:  SetDateTime updates the global variable
  14949.     Time to the value of the secs parameter.
  14950.     _________________________________________________________________
  14951.  
  14952.  
  14953.     Result codes    noErr       No error
  14954.                     clkWrErr    Time written did not verify
  14955.                     clkRdErr    Unable to read clock
  14956. \ Date2Secs
  14957. 25
  14958. PROCEDURE Date2Secs (date: DateTimeRec; VAR secs: LONGINT);
  14959.  
  14960.     _________________________________________________________________
  14961.  
  14962.     Trap macro  _Date2Secs
  14963.  
  14964.     On entry    A0:  pointer to date/time record
  14965.  
  14966.     On exit     D0:  secs (long word)
  14967.     _________________________________________________________________
  14968.  
  14969.     Date2Secs takes the given date/time record, converts it to the
  14970. corresponding number of seconds elapsed since midnight, January 1,
  14971. 1904, and returns the result in the secs parameter. The dayOfWeek
  14972. field of the date/time record is ignored. The values passed in the
  14973. year and month fields should be within their allowable ranges, or
  14974. unpredictable results may occur. The remaining four fields of the
  14975. date/time record may contain any value. For example, September 35 will
  14976. be interpreted as October 4, and you could specify the 300th day of the
  14977. year as January 300.
  14978. \ Secs2Date
  14979. 25
  14980. PROCEDURE Secs2Date (secs: LONGINT; VAR date: DateTimeRec);
  14981.  
  14982.     ________________________________________________________________
  14983.  
  14984.     Trap macro  _Secs2Date
  14985.  
  14986.     On entry    D0:  secs (long word)
  14987.  
  14988.     On exit     A0:  pointer to date/time record
  14989.     ________________________________________________________________
  14990.  
  14991.  
  14992.     Secs2Date takes a number of seconds elapsed since midnight,
  14993. January 1, 1904 as specified by the secs parameter, converts it to the
  14994. corresponding date and time, and returns the corresponding date/time
  14995. record in the date parameter.
  14996. \ GetTime
  14997. 25
  14998. PROCEDURE GetTime (VAR date: DateTimeRec);   [Not in ROM]
  14999.  
  15000.     GetTime takes the number of seconds elapsed since midnight,
  15001. January 1, 1904 (obtained by calling GetDateTime), converts that value
  15002. into a date and time (by calling Secs2Date), and returns the result in
  15003. the date parameter.
  15004. \ SetTime
  15005. 25
  15006. PROCEDURE SetTime (date: DateTimeRec);   [Not in ROM]
  15007.  
  15008.     SetTime takes the date and time specified by the date parameter,
  15009. converts it into the corresponding number of seconds elapsed since
  15010. midnight, January 1, 1904 (by calling Date2Secs), and then writes that
  15011. value to the clock chip as the current date time (by calling
  15012. SetDateTime).
  15013. \ InitUtil
  15014. 25
  15015. FUNCTION InitUtil : OSErr;
  15016.  
  15017.     _________________________________________________________________
  15018.  
  15019.     Trap macro  _InitUtil
  15020.  
  15021.     On exit     D0:  result code (word)
  15022.     _________________________________________________________________
  15023.  
  15024.  
  15025.     InitUtil copies the contents of parameter RAM into 20 bytes of low
  15026. memory and copies the date and time from the clock chip into its own
  15027. low-memory location. This routine is called at system startup; you'll
  15028. probably never need to call it yourself.
  15029.  
  15030.  
  15031.     _________________________________________________________________
  15032.  
  15033.     Assembly-language note:  InitUtil copies parameter RAM into 20
  15034.     bytes starting at the address SysParam and copies the date and
  15035.     time into the global variable Time.
  15036.     _________________________________________________________________
  15037.  
  15038.     If the validity status in parameter RAM is not $A8 when InitUtil is
  15039. called, an error is returned as the result code, and the default values
  15040. (given earlier in the "ParameterRAM" section) are read into the los-
  15041. memory copy of parameter RAM; these values are then written to the
  15042. clock chip itself.
  15043.  
  15044.     Result codes    noErr       No error
  15045.                     prInitErr   Validity status not $A8
  15046. \ GetSysPPtr
  15047. 25
  15048. FUNCTION GetSysPPtr : SysPPtr;   [Not in ROM]
  15049.  
  15050.     GetSysPPtr returns a pointer to the low-memory copy of parameter
  15051. RAM. You can examine the values stored in its various fields, or to
  15052. change them before calling WriteParam (below).
  15053. \ WriteParam
  15054. 25
  15055. FUNCTION WriteParam : OSErr;
  15056.  
  15057.     _________________________________________________________________
  15058.  
  15059.     Trap macro  _WriteParam
  15060.  
  15061.     On entry    A0:  SysParam (pointer)
  15062.                 D0:  MinusOne (long word)
  15063.  
  15064.                  (You have to pass the values of these global
  15065.                   variables for historical reasons.)
  15066.  
  15067.     On exit     D0:  result code (word)
  15068.     _________________________________________________________________
  15069.  
  15070.  
  15071.     WriteParam writes the low-memory copy of parameter RAM to the clock
  15072. chip. You should previously have called GetSysPPtr and changed
  15073. selected values as desired.
  15074.  
  15075.     WriteParam also attempts to verify the values written by reading
  15076. them back in and comparing them to the values in the low-memory copy.
  15077.  
  15078. (note)
  15079.     If you've accidentally written incorrect values into
  15080.     parameter RAM, the system may not be able to start up.
  15081.     If this happens, you can reset parameter RAM by removing
  15082.     the battery, letting the Macintosh sit turned off for
  15083.     about five minutes, and then putting the battery back in.
  15084.  
  15085.  
  15086.     Result code noErr       No error
  15087.                 prWrErr     Parameter RAM written did not verify
  15088. \ Enqueue
  15089. 25
  15090. PROCEDURE Enqueue (qElement: QElemPtr; theQueue: QHdrPtr);
  15091.  
  15092.     ________________________________________________________________
  15093.  
  15094.     Trap macro  _Enqueue
  15095.  
  15096.     On entry    A0:  qElement (pointer)
  15097.                 A1:  theQueue (pointer)
  15098.  
  15099.     On exit     A1:  theQueue (pointer)
  15100.     ________________________________________________________________
  15101.  
  15102.     Enqueue adds the queue entry pointer to by qElement to the end of
  15103. the queue specified by theQueue.
  15104.  
  15105. (note)
  15106.     Interrupts are disabled for a short time while the queue
  15107.     is updated.
  15108. \ Dequeue
  15109. 25
  15110. FUNCTION Dequeue (qElement: QElemPtr; theQueue: QHdrPtr) : OSErr;
  15111.  
  15112.     _________________________________________________________________
  15113.  
  15114.     Trap macro  _Dequeue
  15115.  
  15116.     On entry    A0:  qElement (pointer)
  15117.                 A1:  theQueue (pointer)
  15118.  
  15119.     On exit     A1:  theQueue (pointer)
  15120.                 D0:  result code (word)
  15121.     _________________________________________________________________
  15122.  
  15123.  
  15124.     Dequeue removes the queue entry pointed to by qElement from the
  15125. queue specified by theQueue (without deallocating the entry) and adjusts
  15126. other entries in the queue accordingly.
  15127.  
  15128. (note)
  15129.     The note under Enqueue above also applies here. In this
  15130.     case, the amount of time interrupts are disabled depends
  15131.     on the length of the queue and the position of the entry
  15132.     in the queue.
  15133.  
  15134. (note)
  15135.     To remove all entries from a queue, you can just clear
  15136.     all the fields of the queue's header.
  15137.  
  15138.  
  15139.     Result codes    noErr       No error
  15140.                     qErr        Entry not in specified queue
  15141.  
  15142.  
  15143.  
  15144.  
  15145. \ GetTrapAddress
  15146. 25
  15147. FUNCTION GetTrapAddress (trapNum: INTEGER) : LONGINT;
  15148.  
  15149.     _________________________________________________________________
  15150.  
  15151.     Trap macro  _GetTrapAddress
  15152.  
  15153.     On entry    D0:  trapNum (word)
  15154.  
  15155.     On exit     A0:  address of routine
  15156.     _________________________________________________________________
  15157.  
  15158.  
  15159.     GetTrapAddress returns the address of a routine currently installed
  15160. in the trap dispatch table under the trap number designated by trapNum.
  15161. To find out the trap number for a particular routine, see Appendix B.
  15162. \ SetTrapAddress
  15163. 25
  15164. PROCEDURE SetTrapAddress (trapAddr: LONGINT; trapNum: INTEGER);
  15165.  
  15166.  
  15167.     _________________________________________________________________
  15168.  
  15169.     Trap macro  _SetTrapAddress
  15170.  
  15171.     On entry    A0:  trapAddr (address)
  15172.                 D0:  trapNum (word)
  15173.     _________________________________________________________________
  15174.  
  15175.  
  15176.     SetTrapAddress installs in the trap dispatch table a routine whose
  15177. address is trapAddr; this routine is installed under the trap number
  15178. designated by trapNum.
  15179.  
  15180. (note)
  15181.     Remember, the trap dispatch table can address locations
  15182.     within a range of 64K bytes from the base address of ROM
  15183.     or RAM.
  15184. \ Delay
  15185. 25
  15186. PROCEDURE Delay (numTicks: LONGINT; VAR finalTicks: LONGINT);
  15187.  
  15188.     _______________________________________________________________
  15189.  
  15190.     Trap macro  _Delay
  15191.  
  15192.     On entry    A0:  numTicks (long word)
  15193.  
  15194.     On exit     D0:  finalTicks (long word)
  15195.     _______________________________________________________________
  15196.  
  15197.     Delay causes the system to wait for the number of ticks (sixtieths
  15198. of a second) specified by numTicks, and returns in finalTicks the total
  15199. number of ticks from system startup to the end of the delay.
  15200.  
  15201. (warning)
  15202.     Do not rely on the duration of the delay being exact; it
  15203.     will usually be accurate within one tick, but may be off
  15204.     more than that. The Delay procedure enables all
  15205.     interrupts and checks the tick count that's incremented
  15206.     during the vertical retrace interrupt; however, it's
  15207.     possible for this interrupt to be disabled by other
  15208.     interrupts, in which case the duration of the delay will
  15209.     not be exactly what you requested.
  15210. \ SysBeep
  15211. 25
  15212. PROCEDURE SysBeep (duration: INTEGER);
  15213.  
  15214.     SysBeep causes the system to beep for approximately the number of
  15215. ticks specified by the duration parameter. The sound decays from loud
  15216. to soft; after about five seconds it's inaudible. The initial volume of
  15217. the beep depends on the current speaker volume setting, which the user
  15218. can adjust with the Control Panel desk accessory. If the speaker
  15219. volume has been set to 0 (silent), SysBeep instead causes the menu bar
  15220. to blink once.
  15221. \ LNew
  15222. 26
  15223. FUNCTION LNew (rView,dataBounds: Rect; cSize: Point; theProc: INTEGER;
  15224.                 theWindow: WindowPtr; drawIt,hasGrow,
  15225.                 scrollHoriz,scrollVert: BOOLEAN) : ListHandle;
  15226.  
  15227.     Call LNew to create a new list. It returns a handle to the new list.
  15228. The list’s grafPort is set to theWindow’s port. If drawIt is FALSE,
  15229. the list is not displayed.
  15230.  
  15231.     RView specifies, in the local coordinates of theWindow, the
  15232. rectangle in which the list will be displayed. (Remember that this
  15233. doesn’t include space for scroll bars. If the list, including scroll
  15234. bars, is to fill the entire window, rView should be 15 points smaller in
  15235. each dimension than theWindow’s portRect.)
  15236.  
  15237.     DataBounds is the rectangle for specifying the initial array
  15238. dimensions of the list. For example to preallocate space for a list
  15239. that’s 5 cells across by 10 cells down, you should set dataBounds to
  15240. (0,0)(5,10). If you want to allocate the space for a one-column list,
  15241. set dataBounds to (0,0)(1,0) and use LAddRow.
  15242.  
  15243.     CSize.h and cSize.v are the desired height and width of each cell in
  15244. pixels; if they’re not specified, a default cell size is calculated
  15245. (as described above).
  15246.  
  15247.     TheProc is the resource ID of your list definition procedure; for
  15248. a text-only list, pass 0 and the default list definition procedure
  15249. (about 150 bytes in size) will be used. The list definition procedure
  15250. is called to initialize itself after all other list record fields have
  15251. been initialized; thus, it can use any of the values in the list record
  15252. (or set particular fields, such as the indent distance).
  15253.  
  15254.     If hasGrow is TRUE, the scroll bars are sized so that there’s room
  15255. for a size box in the standard position. It’s up to the program to
  15256. display the size box (using the Window Manager procedure DrawGrowIcon).
  15257. If scrollHoriz is TRUE, a horizontal scroll bar is placed immediately
  15258. below rView and all horizontal scrolling functions are implemented.
  15259. If scrollVert is TRUE, a vertical scroll bar is placed immediately to
  15260. the right of rView and all vertical scrolling functions are implemented.
  15261.  
  15262.     The visible rectangle is set to contain as many cells of cSize
  15263. (or the default) as will fit into rView. If the cells do not fit
  15264. exactly into rView, the visible rectangle is rounded up to the nearest
  15265. cell. Scrolling will always allow all cells to be fully displayed.
  15266. The selection flags are set to 0, and the active flag is set to TRUE.
  15267.  
  15268.  
  15269. Note:  Scrolling looks best if rView is a multiple of cSize.v in height.
  15270.  
  15271. \ LDispose
  15272. 26
  15273. PROCEDURE LDispose (lHandle: ListHandle);
  15274.  
  15275.     Call LDispose when you are through using a list. It issues a close
  15276. call to the list definition procedure, and calls the Memory Manager
  15277. procedure DisposHandle for the data handle, the Control Manager
  15278. procedure DisposeControl for both scroll bars (if they’re there), and
  15279. DisposHandle for the list record.
  15280.  
  15281. Note:  Calling LDispose is much faster than deleting one row at a time.
  15282.  
  15283. \ LAddColumn
  15284. 26
  15285. FUNCTION LAddColumn (count,colNum: INTEGER; lHandle: ListHandle)
  15286.                     : INTEGER;
  15287.  
  15288.     LAddColumn inserts into the given list the number of columns
  15289. specified by the count parameter, starting at the column specified by
  15290. colNum. Column numbers that are greater than or equal to colNum are
  15291. increased by count. If colNum is not within dataBounds, new last
  15292. columns are added. The number of the first added column is returned
  15293. and dataBounds.right is increased by count. All cells added are empty.
  15294. If there are no cells (because dataBounds.top = dataBounds.bottom), no
  15295. cells are added, but dataBounds is still extended. If drawing is on and
  15296. the added columns (which are empty) are visible, the list and its
  15297. scrollbars are updated.
  15298.  
  15299. \ LAddRow
  15300. 26
  15301. FUNCTION LAddRow (count,rowNum: INTEGER; lHandle: ListHandle) : INTEGER;
  15302.  
  15303.     LAddRow inserts the number of rows specified by the count parameter,
  15304. starting at the row specified by rowNum. Row numbers that are greater
  15305. than or equal to rowNum are increased by count. If rowNum is not within
  15306. dataBounds, new last rows are added. The number of the first added row
  15307. is returned, and dataBounds.bottom is increased by count. All cells
  15308. added are empty. If there are no cells (because dataBounds.left =
  15309. dataBounds.right), no cells are added, but dataBounds is still extended.
  15310. If drawing is on and the added rows (which are empty) are visible, the
  15311. list and its scroll bars are updated.
  15312.  
  15313. \ LDelColumn
  15314. 26
  15315. PROCEDURE LDelColumn (count,colNum: INTEGER; lHandle: ListHandle);
  15316.  
  15317.     LDelColumn deletes the number of columns specified by the count
  15318. parameter, starting with the column specified by colNum. Column
  15319. numbers that are greater than colNum are decreased by count. If colNum
  15320. is not within dataBounds, nothing is done. DataBounds.right is
  15321. decreased by count. If drawing is on and the deleted columns were
  15322. visible, the list and its scroll bars are updated.
  15323.  
  15324.     If count is 0, or colNum = dataBounds.left AND count  > =
  15325. dataBounds.right – dataBounds.left all the data in the list is quickly
  15326. deleted, dataBounds.right is set to dataBounds.left, and the number of
  15327. rows is left unchanged.
  15328.  
  15329. \ LDelRow
  15330. 26
  15331. PROCEDURE LDelRow (count,rowNum: INTEGER; lHandle: ListHandle);
  15332.  
  15333.     LDelRow deletes the number of rows specified by the count parameter,
  15334. starting with the row specified by rowNum. Row numbers that are greater
  15335. than rowNum are decreased by count. If rowNum is not within dataBounds,
  15336. nothing is done. DataBounds.bottom is decreased by count. If drawing
  15337. is on and the deleted rows were visible, the list and its scroll bars
  15338. are updated.
  15339.  
  15340.     If count is 0, or rowNum = dataBounds.top AND count > =
  15341. dataBounds.bottom – dataBounds.top all the data in the list is quickly
  15342. deleted, dataBounds.bottom is set to dataBounds.top, and the number of
  15343. columns is left unchanged.
  15344.  
  15345. \ LAddToCell
  15346. 26
  15347. PROCEDURE LAddToCell (dataPtr: Ptr; dataLen: INTEGER; theCell: Cell;
  15348.                         lHandle: ListHandle);
  15349.  
  15350.     LAddToCell appends the data pointed to by dataPtr and of length
  15351. dataLen to the cell specified by theCell in lHandle. If drawing is off,
  15352. you must turn drawing on and call LDraw (or LUpdate) to display the
  15353. cell’s new value.
  15354.  
  15355. \ LClrCell
  15356. 26
  15357. PROCEDURE LClrCell (theCell: Cell; lHandle: ListHandle);
  15358.  
  15359.     LClrCell clears the contents of the specified cell (by setting the
  15360. length to 0). If theCell is not a valid cell, nothing is done. If
  15361. drawing is off, you must turn drawing on and call LDraw to display
  15362. the cell’s new value (or simply call the Window Manager procedure
  15363. InvalRect).
  15364.  
  15365. \ LGetCell
  15366. 26
  15367. PROCEDURE LGetCell (dataPtr: Ptr; VAR dataLen: INTEGER; theCell: Cell;
  15368.                     lHandle: ListHandle);
  15369.  
  15370.     Given a cell in theCell, LGetCell copies the cell’s data to the
  15371. location specified by dataPtr; dataLen is the maximum number of bytes
  15372. allowed. If the data is longer than dataLen, only dataLen bytes are
  15373. copied into the location specified by dataPtr. If the data is shorter
  15374. than dataLen, dataLen is set to the true length of the cell’s data.
  15375.  
  15376. \ LSetCell
  15377. 26
  15378. PROCEDURE LSetCell (dataPtr: Ptr; dataLen: INTEGER; theCell: Cell;
  15379.                     lHandle: ListHandle);
  15380.  
  15381.     LSetCell places the data pointed to by dataPtr and of length dataLen
  15382. into the specified cell. It replaces any data that was already in the
  15383. cell. If dataLen is 0, this is equivalent to LClrCell. If theCell is
  15384. not a valid cell, nothing is done. If drawing is off, you must turn
  15385. drawing on and call LDraw (or LUpdate) to display the cell’s new value.
  15386.  
  15387. \ LCellSize
  15388. 26
  15389. PROCEDURE LCellSize (cSize: Point; lHandle: ListHandle);
  15390.  
  15391.     LCellSize sets the cellSize field in the list record to cSize and
  15392. updates the visible rectangle to contain cells of this size. This
  15393. command should be used only before any cells have been drawn.
  15394.  
  15395. \ LGetSelect
  15396. 26
  15397. FUNCTION LGetSelect (next: BOOLEAN; VAR theCell: Cell;
  15398.                     lHandle: ListHandle) : BOOLEAN;
  15399.  
  15400.     If next is FALSE, LGetSelect returns TRUE if the specified cell is
  15401. selected, or FALSE if not. If next is TRUE, LGetSelect returns in c the
  15402. cell coordinates of the next selected cell in the row that is greater
  15403. than or equal to theCell. If there are no more cells in the row, it
  15404. returns in theCell the cell coordinates of the next selected cell in the
  15405. next row. If there are no more rows, FALSE is returned.
  15406.  
  15407. \ LSetSelect
  15408. 26
  15409. PROCEDURE LSetSelect (setIt: BOOLEAN; theCell: Cell;
  15410.                         lHandle: ListHandle);
  15411.  
  15412.     If setIt is TRUE, LSetSelect selects the cell and redraws if it is
  15413. visible and was previously unselected. If setIt is FALSE, it deselects
  15414. the cell and redraws if necessary.
  15415.  
  15416. \ LClick
  15417. 26
  15418. FUNCTION LClick (pt: Point; modifiers: INTEGER; lHandle: ListHandle)
  15419.                     : BOOLEAN;
  15420.  
  15421.     Call LClick when there is a mouse-down event in the destination
  15422. rectangle or its scroll bars. Pt is the mouse location in local
  15423. coordinates. Modifiers is the modifiers word from the event record.
  15424. LHandle is the list to be tracked. The result is TRUE if a double-click
  15425. occurred (and the two clicks took place within the same cell).
  15426.  
  15427.     LClick keeps control until the mouse is released; each time through
  15428. its inner loop, it calls the routine whose pointer is in the lClikLoop
  15429. field of the list record.
  15430.  
  15431.     If the mouse is in the visible rectangle, cells are selected
  15432. according to the state of the modifiers and the selection flags. If the
  15433. mouse was in the cells but is dragged outside the list’s rectangle, the
  15434. list is auto-scrolled. If the mouse was in a control, the control’s
  15435. definition procedure is called to track the mouse. To discover which
  15436. cell was clicked in, use the LLastClick function.
  15437.  
  15438. \ LLastClick
  15439. 26
  15440. FUNCTION LLastClick (lHandle: ListHandle) : Cell;
  15441.  
  15442.     LLastClick returns the cell coordinates of the last cell clicked in.
  15443. If no cell has been clicked in since LNew, the value returned (for both
  15444. integers) is negative.
  15445.  
  15446. Note:   The value returned by this call is not the last cell
  15447.         double-clicked in, or the last cell selected, but merely the
  15448.         last cell clicked in.
  15449.  
  15450. \ LFind
  15451. 26
  15452. PROCEDURE LFind (VAR offset,len: INTEGER; theCell: Cell;
  15453.                     lHandle: ListHandle);
  15454.  
  15455.     Given a cell in theCell, LFind returns the offset and the length in
  15456. bytes of the cell’s data. If an invalid cell is specified, offset and
  15457. len are set to –1. A similar procedure, LGetCell, is more convenient to
  15458. use from Pascal.
  15459.  
  15460. \ LNextCell
  15461. 26
  15462. FUNCTION LNextCell (hNext,vNext: BOOLEAN; VAR theCell: Cell;
  15463.                     lHandle: ListHandle) : BOOLEAN;
  15464.  
  15465.     Given a cell in theCell, LNextCell returns in theCell the next cell
  15466. in the list. If both hNext and vNext are TRUE, theCell is first
  15467. advanced to the next cell in the row. If there are no more cells in the
  15468. row, theCell is set to the first cell in the next row. If there are no
  15469. more rows, FALSE is returned. If only hNext is TRUE, theCell is
  15470. advanced within the current row. If only vNext is TRUE, theCell is
  15471. advanced within the current column. FALSE is returned if there are no
  15472. remaining cells in the row or column.
  15473.  
  15474. \ LRect
  15475. 26
  15476. PROCEDURE LRect (VAR cellRect: Rect; theCell: Cell; lHandle: ListHandle)
  15477.  
  15478.     LRect returns in cellRect the local (QuickDraw) coordinates of the
  15479. cell specified by theCell. If an invalid cell is specified, (0,0)(0,0)
  15480. is returned in cellRect.
  15481.  
  15482. \ LSearch
  15483. 26
  15484. FUNCTION LSearch (dataPtr: Ptr; dataLen: INTEGER; searchProc: Ptr;
  15485.                     VAR theCell: Cell; lHandle: ListHandle) : BOOLEAN;
  15486.  
  15487.     LSearch searches for the first cell greater than or equal to theCell
  15488. that contains the specified data. If a cell containing matching data is
  15489. found, the function result TRUE is returned, and the cell coordinates
  15490. are returned in theCell. If searchProc is NIL, the International
  15491. Utilities Package function IUMagIDString is called to compare the
  15492. specified data with the contents of each cell. If searchProc is not
  15493. NIL, the routine pointed to by searchProc is called.
  15494.  
  15495. Note:  Your searchProc should have the same parameters as the
  15496.         IUMagIDString function.
  15497.  
  15498. \ LSize
  15499. 26
  15500. PROCEDURE LSize (listWidth,listHeight: INTEGER; lHandle: ListHandle);
  15501.  
  15502.     You’ll usually call LSize immediately after the Window Manager
  15503. procedure SizeWindow. It causes the bottom right of the list to be
  15504. adjusted so that the list is the width and height indicated by listWidth
  15505. and listHeight. The contents of the list and the scroll bars are
  15506. adjusted and redrawn as necessary. The values of listWidth and
  15507. listHeight do not include the scroll bars; for a list that entirely
  15508. fills the window, listWidth and listHeight should be 15 less than the
  15509. portRect if both scroll bars are present.
  15510.  
  15511. \ LDraw
  15512. 26
  15513. PROCEDURE LDraw (theCell: Cell; lHandle: ListHandle);
  15514.  
  15515.     Call LDraw after updating a cell’s data or selection status. (You
  15516. can achieve the same result by invalidating the cell’s rectangle and
  15517. calling LUpdate in response to the update event.)  The List Manager
  15518. makes its grafPort the current port, sets the clipping region to
  15519. the cell’s rectangle, and calls the list definition procedure to draw
  15520. the cell. It restores the clipping region and port before exiting.
  15521.  
  15522. \ LDoDraw
  15523. 26
  15524. PROCEDURE LDoDraw (drawIt: BOOLEAN; lHandle: ListHandle);
  15525.  
  15526.     LDoDraw sets the List Manager’s drawing mode to the state specified
  15527. by drawIt. If drawIt is TRUE, changes made by most List Manager calls
  15528. will cause some sort of drawing to take place. If drawIt is FALSE, all
  15529. cell drawing is disabled. (Two exceptions:  The scroll bars are still
  15530. updated after LSize, and the scroll arrows are still highlighted if the
  15531. user clicks them.)
  15532.  
  15533.     The recommended use of LDoDraw is to disable drawing while you’re
  15534. building a list (that is, adding rows or columns, setting or changing
  15535. cell values, or setting default selections). Once you’ve finished
  15536. building the list, you should then re-enable drawing. In general,
  15537. drawing should be on while you’re in your event loop and dispatching
  15538. events to the List Manager.
  15539.  
  15540. \ LScroll
  15541. 26
  15542. PROCEDURE LScroll (dCols,dRows: INTEGER; lHandle: ListHandle);
  15543.  
  15544.     LScroll scrolls the given list by the number of columns and rows
  15545. specified in dCols and dRows, either positively (down and to the right)
  15546. or negatively (up and to the left). Scrolling is pinned to the list’s
  15547. dataBounds. If drawing is on, LScroll does all necessary updating of
  15548. the screen.
  15549.  
  15550. \ LAutoScroll
  15551. 26
  15552. PROCEDURE LAutoScroll   (lHandle: ListHandle);
  15553.  
  15554.     For the given list, LAutoScroll scrolls the list until the first
  15555. selected cell is visible. It automatically places the first selected
  15556. cell in the top left corner of the visible rectangle.
  15557.  
  15558. \ LUpdate
  15559. 26
  15560. PROCEDURE LUpdate (theRgn: RgnHandle; lHandle: ListHandle);
  15561.  
  15562.     LUpdate should be called in response to an update event. TheRgn
  15563. should be set to the visRgn of the list’s port (for more details, see
  15564. the BeginUpdate procedure in the Window Manager chapter). It redraws
  15565. any visible cells in lHandle that intersect theRgn. It also redraws
  15566. the controls, if necessary.
  15567.  
  15568. \ LActivate
  15569. 26
  15570. PROCEDURE LActivate (act: BOOLEAN; lHandle: ListHandle);
  15571.  
  15572.     Call LActivate to activate or deactivate the list specified by
  15573. lHandle (in response to an activate event in the window containing the
  15574. list). The act parameter should be set to TRUE to activate the list, or
  15575. FALSE to deactivate the list. LActivate highlights or unhighlights the
  15576. selections, and shows or hides the scroll bars (but not the size box, if
  15577. any).